Install & Compatibility
Where this runs
tested against v0.14.0 · pip install
no network on importno background threads
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.920 runs
installs and imports cleanly · install 0.0s · import 0.016s · 104.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.1s · import 0.015s · 106MB
108MB installed
● package 108MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TwoBitFile
✓ from bx.seq.twobit import TwoBitFile
MAFWriter
✓ from bx.align.maf import MAFWriter
Interval
✓ from bx.intervals.io import Interval
Header
✓ from bx.align.fasta import Header
This quickstart demonstrates how to interact with `bx-python` for common bioinformatics tasks. It shows how to use `TwoBitFile` to access genomic sequences (note: a valid .2bit file is required for this part to fully run) and how to construct and write a simple MAF (Multiple Alignment Format) block to standard output using `MAFWriter`.
from bx.seq.twobit import TwoBitFile
import os
# This is a placeholder for a real .2bit file
# In a real scenario, you'd open an existing file.
# For demonstration, we'll simulate a file path.
twobit_file_path = os.environ.get('BX_TWOBIT_FILE', 'example.2bit')
# Create a dummy .2bit file for demonstration if it doesn't exist
# This part would typically not be in a quickstart but is here for runnability.
if not os.path.exists(twobit_file_path):
try:
# TwoBitFile constructor expects a file-like object or a path to an existing file
# For a runnable example, we would need to *create* a valid .2bit file or skip this section.
# Given the complexity, let's illustrate reading an assumed existing file.
# This part of the quickstart is illustrative rather than fully runnable without a .2bit file.
print(f"Please provide a valid .2bit file at {twobit_file_path} to run this example.")
print("Example: Download one from UCSC genome browser, e.g., 'hg38.2bit'")
# Example of how you would *use* it if the file exists:
# with open(twobit_file_path, 'rb') as f:
# tb = TwoBitFile(f)
# print(f"Sequence 'chr1' length: {tb['chr1'].length}")
# print(f"Sequence 'chr1' first 10 bases: {tb['chr1'].get(0, 10)}")
except Exception as e:
print(f"Could not create or open dummy .2bit file for quickstart: {e}")
print("Skipping TwoBitFile quickstart example.")
# Example of using MAF (Multiple Alignment Format) writer
from bx.align.maf import MAFWriter, MAFAlignment, MAFBlock, MAFComponent
import sys
print("\nDemonstrating MAFWriter:")
writer = MAFWriter(sys.stdout)
alignment = MAFAlignment()
block = MAFBlock()
# Create components for a block
comp1 = MAFComponent()
comp1.src = 'hg38.chr1'
comp1.start = 100
comp1.size = 10
comp1.strand = '+'
comp1.srcSize = 248956422
comp1.text = 'ATGCATGCAT'
comp2 = MAFComponent()
comp2.src = 'mm10.chrX'
comp2.start = 50
comp2.size = 10
comp2.strand = '-'
comp2.srcSize = 171031299
comp2.text = 'ATGCATGCAT'
block.components.append(comp1)
block.components.append(comp2)
alignment.append(block)
writer.write(alignment)
print("MAF example written to stdout.")
Debug
Known issues
breakingPython 3.8 support was dropped in `bx-python` v0.14.0. If you are using an older Python version, you must upgrade Python or pin an older `bx-python` version.fixUpgrade Python to 3.9 or higher (recommended), or install `bx-python<0.14.0`.
affects: >=0.14.0
breakingThe `psyco` module and `bx.cookbook.progress_bar` module were removed in `bx-python` v0.13.0. Any code depending on these modules will break.fixRemove all references to `psyco` (which only supported Python <= 2.6) and `bx.cookbook.progress_bar`. For progress bars, consider alternatives like `tqdm`.
affects: >=0.13.0
breakingIndexing `TwoBitFile` sequences changed from expecting `bytes` to `str` in `bx-python` v0.9.0. Using `bytes` for sequence names will result in errors.fixEnsure that sequence names used for indexing `TwoBitFile` objects are Python `str` objects, not `bytes`.
affects: >=0.9.0
gotchaOlder versions of NumPy (pre-1.24) used `np.float`, which is deprecated in newer NumPy versions. `bx-python` has addressed compatibility, but issues might arise if using specific older `bx-python` versions with new NumPy or vice-versa.fixEnsure `bx-python` and `numpy` versions are compatible. `bx-python` >= 0.10.0 provides fixes for `np.float` deprecation. If experiencing issues, try upgrading both packages or ensuring your NumPy is not extremely old/new compared to your `bx-python`.
affects: All versions, depending on NumPy version interaction
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bx.cookbook.progress_bar'
The `bx.cookbook.progress_bar` module was removed in `bx-python` version 0.13.0.
fixRemove any code that attempts to import or use `bx.cookbook.progress_bar`. If a progress bar is needed, use a third-party library like `tqdm`.
TypeError: sequence indices must be integers or slices, not bytes
Prior to `bx-python` v0.9.0, `TwoBitFile` sequences could be indexed by `bytes`. From v0.9.0 onwards, `str` is required.
fixConvert any `bytes` sequence names to `str` before indexing `TwoBitFile`. For example, `tb[b'chr1']` should become `tb['chr1']`.
ImportError: cannot import name 'cookbook' from 'bx' (or similar for other submodules)
Incorrect import path used, or trying to import a module that was moved/removed. A fix was applied in v0.13.0 for `bx.cookbook`'s import.
fixVerify the exact import path from the `bx-python` documentation for your specific version. Ensure you are importing from `bx.cookbook.tools` or `bx.align.maf` etc., rather than just `bx.cookbook` directly.
RuntimeError: Python 3.8 is not supported
`bx-python` v0.14.0 and newer versions dropped support for Python 3.8.
fixUpgrade your Python environment to Python 3.9 or higher. Alternatively, if you must use Python 3.8, install an older compatible version of `bx-python`, e.g., `pip install 'bx-python<0.14.0'`.
Upgrade
Version history
0.14.0latest on PyPI · released Jul 30, 2025
Audit
Dependencies
numpyrequiredUsed for numerical operations, especially in alignment and interval modules. Compatibility changes are common across bx-python versions.