Install & Compatibility
Where this runs
tested against v1.1.3 · 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.107s · 19.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.9s · import 0.095s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fetch
✓ from mmtf import fetch
MMTFDecoder
✓ from mmtf.decoder import MMTFDecoder
✗ from mmtf import MMTFDecoder
MMTFDecoder is typically accessed via the mmtf.decoder submodule, though 'fetch' is the recommended entry point for common use cases.
This quickstart demonstrates how to fetch and access basic structural information from a PDB entry using the MMTF format. It retrieves the structure for PDB ID 4CUP and prints its code, number of chains, formal charges for the first group, and the count of bioassemblies.
from mmtf import fetch
# Get the data for a PDB structure (e.g., 4CUP)
decoded_data = fetch("4CUP")
print(f"PDB Code: {decoded_data.structure_id} has {decoded_data.num_chains} chains")
# Show the charge information for the first group
if decoded_data.group_list and decoded_data.group_list[0]:
group_name = decoded_data.group_list[0].get("groupName", "N/A")
charges = decoded_data.group_list[0].get("formalChargeList", [])
print(f"Group name: {group_name} has the following atomic charges: {','.join(map(str, charges))}")
# Show how many bioassemblies it has
print(f"PDB Code: {decoded_data.structure_id} has {len(decoded_data.bio_assembly)} bioassemblies")
Debug
Known issues
breakingRCSB PDB ceased serving MMTF data by default as of July 2, 2024. Users relying on direct downloads from RCSB PDB in MMTF format will need to switch to BinaryCIF (BCIF) or find alternative MMTF data sources.fixMigrate data fetching mechanisms to use BinaryCIF (BCIF) format or obtain MMTF files from other archives. Consider libraries supporting BCIF for new data.
affects: All versions, for data fetching directly from RCSB PDB
gotchaThe `mmtf-python` library has not had major feature updates since its 1.1.3 release in July 2022. While functional, it may encounter compatibility issues with very recent Python versions (e.g., Python 3.10+) or newer versions of its dependencies.fixTest thoroughly with your specific Python environment and dependency versions. Consider pinning dependency versions if issues arise.
affects: 1.1.3 and older
gotchaWhen migrating code from Python 2 to Python 3, be aware of syntax changes, particularly `print` becoming a function (`print()`). Incorrect usage may lead to `SyntaxError` or `TypeError`.fixEnsure all `print` statements are converted to `print()` functions and other Python 2 specific syntax is updated.
affects: Code originally written for Python 2
gotchaOlder versions (prior to v1.0.10) had issues with leaking open file handles, which could lead to resource exhaustion in long-running applications or when processing many files.fixUpgrade to version 1.0.10 or newer to benefit from the fix for file handle leaks.
affects: < 1.0.10
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mmtf'
The 'mmtf-python' library has not been installed or the Python environment where it's installed is not active.
fixInstall the library using `pip install mmtf-python` or `conda install -c conda-forge mmtf-python`.
TypeError: 'MMTFDecoder' object is not callable
Attempting to call `MMTFDecoder` directly as a function instead of importing and instantiating it, or more commonly, trying to call the `mmtf` module itself when meaning to use a function like `fetch`.
fixUse the high-level `mmtf.fetch()` function for direct PDB ID retrieval, or correctly import and instantiate `MMTFDecoder` from `mmtf.decoder` if manual decoding is needed. Example: `from mmtf import fetch; data = fetch('1ABC')`. AttributeError: 'DecodedData' object has no attribute 'some_invalid_attribute'
Attempting to access an attribute (e.g., `structure_id`, `num_chains`) that either doesn't exist or is misspelled on the `DecodedData` object returned by `fetch`.
fixConsult the `mmtf-python` documentation or the MMTF specification for the correct attribute names available in the decoded structure. Common attributes include `structure_id`, `num_chains`, `bio_assembly`, `group_list`.
KeyError: 'some_missing_key'
Attempting to access a key within a dictionary-like structure (e.g., `group_list` elements) that is not present in the specific MMTF file's data.
fixUse `.get(key, default_value)` when accessing dictionary keys to prevent `KeyError` if a key might be absent. Example: `group_name = decoded_data.group_list[0].get('groupName', 'Unknown')`. ImportError: cannot import name 'fetch' from 'mmtf'
This usually indicates that the 'fetch' function is not directly exposed at the top level of the 'mmtf' package, or there is a naming conflict/issue with the local environment.
fixEnsure you are using `from mmtf import fetch`. If the error persists, check for any local files named 'mmtf.py' that might be shadowing the installed library. Verify the installed version against documentation.
Upgrade
Version history
1.1.3latest on PyPI · released Jul 6, 2022
Audit
Dependencies
msgpackrequiredRequired for efficient binary serialization and deserialization of MMTF data.
numpyoptionalOften used internally for handling numerical data arrays within decoded structures.