Install & Compatibility
Where this runs
tested against v2.1.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.006s · 17.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.006s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PdbxReader
✓ from pdbx.reader import PdbxReader
For reading mmCIF files.
PdbxWriter
✓ from pdbx.writer import PdbxWriter
For writing mmCIF files.
DataContainer
✓ from pdbx.containers import DataContainer
Represents a data block within an mmCIF file.
load
✓ from pdbx import load
Convenience function for parsing a CIF file object.
loads
✓ from pdbx import loads
Convenience function for parsing a CIF string.
dump
✓ from pdbx import dump
Convenience function for writing DataContainer objects to a CIF file object.
dumps
✓ from pdbx import dumps
Convenience function for serializing DataContainer objects to a CIF string.
This quickstart demonstrates how to parse an mmCIF string, access data within categories, and serialize modified data back to an mmCIF string using the `loads` and `dumps` utility functions, and interacting with `DataContainer` and `DataCategory` objects.
import io
from pdbx import loads, dumps, DataCategory, DataContainer
# Example mmCIF data as a string
mmcif_data = '''
data_testblock
_entry.id test
loop_
_atom_site.id
_atom_site.type_symbol
_atom_site.label_atom_id
1 C CA
2 O O
'''
# Parse the mmCIF string
data_containers = loads(mmcif_data)
# Access data (assuming one data block)
if data_containers:
data_block = data_containers[0]
print(f"Data block ID: {data_block.name}")
# Access a category
atom_site_category = data_block.getObj('atom_site')
if atom_site_category:
print("\nAtom Site Category:")
for i in range(atom_site_category.getRowCount()):
atom_id = atom_site_category.getValue('id', i)
atom_type = atom_site_category.getValue('type_symbol', i)
print(f" ID: {atom_id}, Type: {atom_type}")
else:
print("Atom_site category not found.")
# Modify data (example: add a new item to the entry category)
entry_category = data_block.getObj('entry')
if entry_category:
entry_category.setValue('new_item', 0, 'new_value')
# Serialize the modified data back to a string
modified_mmcif_data = dumps(data_containers)
print("\nModified mmCIF data:\n", modified_mmcif_data)
else:
print("No data containers found.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mmcif_pdbx'
The Python package is installed as 'mmcif-pdbx' but the correct module name to import is 'pdbx'.
fixChange the import statement to `import pdbx` or `from pdbx import load`.
pdbx.errors.PdbxSyntaxError: invalid CIF syntax
The mmCIF file being parsed contains syntax errors, such as incorrect delimiters, unclosed quotes, or malformed data blocks, which the `mmcif-pdbx` parser cannot interpret.
fixInspect the specified line number and surrounding text in the mmCIF file to correct the syntax. Often, this requires manually cleaning or reformatting the CIF data, or using a more robust validator tool to identify issues.
KeyError: '_some_category.some_item'
After loading an mmCIF file, the code attempts to access a data category or data item that is not present in that specific CIF file or is named differently.
fixVerify the exact names of categories and items within the mmCIF file. Use methods to check for the existence of keys (e.g., `if 'my_category' in data_container:`) or provide default values when accessing data.
Upgrade
Version history
2.1.0latest on PyPI · released Apr 26, 2026
Audit
Dependencies
No dependency data recorded yet.