Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BedTool
✓ from pybedtools import BedTool
scripts
✓ import pybedtools.scripts
✗ from pybedtools import scripts
Directly importing 'scripts' can conflict with an 'scripts' module from Anaconda, causing an ImportError. Use `import pybedtools.scripts` or rename your script file if it's named 'scripts.py'.
This quickstart demonstrates how to create `BedTool` objects from existing BED files, perform an intersection operation (like `intersectBed`), and save the results to a new file, including adding a track line.
import pybedtools
import os
# Create dummy files for demonstration
# In a real scenario, these would be your actual genomic files
with open('snps.bed', 'w') as f:
f.write('chr1\t10\t20\tSNP1\n')
f.write('chr1\t30\t40\tSNP2\n')
with open('exons.bed', 'w') as f:
f.write('chr1\t15\t25\tEXON1\n')
f.write('chr1\t35\t45\tEXON2\n')
# Create BedTool objects from files
snps = pybedtools.BedTool('snps.bed')
exons = pybedtools.BedTool('exons.bed')
# Perform an intersection and save the results
# This example saves a new BED file of intersections
# between snps.bed and exons.bed
intersected_bed = snps.intersect(exons)
output_filename = 'snps_in_exons.bed'
intersected_bed.saveas(output_filename, trackline="track name='SNPs in exons' color=128,0,0")
print(f"Intersection results saved to {output_filename}:")
with open(output_filename, 'r') as f:
print(f.read())
# Clean up dummy files
os.remove('snps.bed')
os.remove('exons.bed')
os.remove(output_filename)
Debug
Known issues
breakingPython 3.8 support was removed in pybedtools v0.11.0. Python 3.6 and 3.7 support was dropped in v0.9.1.fixUpgrade to a supported Python version (3.9+ for v0.11.0+, 3.8+ for v0.9.1 to <0.11.0).
affects: >=0.11.0, >=0.9.1
gotchaRepeatedly creating `BedTool` objects, especially within loops, can lead to a 'Too many files open' error.fixMinimize `BedTool` object creation. Many operations can be chained or filtered without creating new intermediate `BedTool` objects. Construct 'streaming' BedTools or apply `filter()` methods upfront to reduce the number of open files.
affects: All versions
gotchapybedtools adheres to 0-based (BED) and 1-based (GFF) coordinate systems in the raw string output, but internally converts all `Interval` object start/stop attributes to 0-based for consistency.fixAlways assume 0-based coordinates when programmatically accessing `Interval` object's `.start` and `.stop` attributes. Be mindful of the output format's conventions when saving to file.
affects: All versions
deprecatedThe `samtools` dependency was removed and replaced by `pysam` for BAM file handling.fixEnsure `pysam` is installed if working with BAM files; direct `samtools` installation is no longer required or supported by pybedtools itself.
affects: <0.7.9
gotchapybedtools relies on the underlying BEDTools executables. If BEDTools issues a warning (e.g., about malformed lines), pybedtools might raise an error and fail to create a `BedTool` object, even if BEDTools itself would produce output.fixPre-process input files to ensure they conform strictly to BEDTools specifications or use `pybedtools.remove_invalid()` to clean them. Review BEDTools documentation for expected file formats.
affects: All versions
Errors
Common errors & fixes
ImportError: cannot import name scripts
This typically occurs when using an Anaconda environment where another package or a user-created script is named 'scripts', shadowing the `pybedtools.scripts` module.
fixChange your import statement to `import pybedtools.scripts` instead of `from pybedtools import scripts`. Alternatively, ensure no other module or script in your Python path is named 'scripts.py'.
IOError: [Errno 24] Too many open files
Too many `BedTool` objects were created, exhausting the operating system's file handle limit. This often happens in loops.
fixRefactor your code to minimize the number of `BedTool` objects created simultaneously. Utilize chaining of methods, `BedTool.filter()`, or `BedTool.each()` to process data efficiently without creating excessive temporary files. Use `pybedtools.cleanup()` if necessary to force deletion of temporary files.
pybedtools.helpers.MalformedBedLineError: Malformed BED line:
The input BED file contains lines that do not conform to the BED format specification (e.g., start coordinate is greater than end, incorrect number of fields, non-tab-delimited fields).
fixInspect the problematic lines in your input file. Ensure `start <= end` and all fields are tab-delimited. Use `pybedtools.remove_invalid()` to attempt to clean the file or manually correct the lines.
command not found: bedtools
The underlying BEDTools executable is not found in the system's PATH. pybedtools acts as a wrapper and requires BEDTools to be installed separately.
fixInstall BEDTools on your system (e.g., `conda install -c bioconda bedtools`). Verify that the `bedtools` command is accessible from your terminal by typing `bedtools --version`.
g++: error: unrecognized command line option '-std=c++11'
This (or similar compilation errors) can occur during `pip install pybedtools` if a suitable C/C++ compiler is not found or is outdated, particularly when building Cython components.
fixEnsure you have a C/C++ compiler installed (e.g., `build-essential` on Linux, Xcode on macOS). If using `pip`, consider installing via Conda (`conda install -c bioconda pybedtools`) which often handles compiler dependencies more robustly.
Upgrade
Version history
0.12.0latest on PyPI · released Mar 16, 2025
Audit
Dependencies
BEDToolsrequiredpybedtools is a Python wrapper for the BEDTools suite of command-line tools, so BEDTools itself must be installed and accessible in the system's PATH.
pysamrequiredUsed for handling BAM files; replaced the direct dependency on `samtools` as of v0.7.9/v0.8.0.
CythonoptionalRequired for pybedtools development; Cythonized C++ files are now shipped with the distribution for end-users.
A C/C++ compilerrequiredNecessary for building C++ components, especially if installing via pip without pre-compiled wheels or if Cython recompilation is triggered.