Install & Compatibility
Where this runs
tested against v1.1.1 · 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.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.000s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MarshalUtil
✓ import mmcif
✗ from mmcif import MarshalUtil
This quickstart demonstrates how to read an mmCIF file from a URL, access its data blocks, and extract information from a specific category using the `MarshalUtil` class.
import os
from rcsb.utils.io.MarshalUtil import MarshalUtil
# Create a MarshalUtil instance for I/O operations
mU = MarshalUtil()
# Define a public mmCIF file URL (e.g., from RCSB PDB)
mmcif_url = "https://files.rcsb.org/download/1ema.cif"
# Load data from the URL. The library can handle both local paths and URLs.
dataContainerList = mU.load(mmcif_url, contentType="mmcif")
if dataContainerList:
# An mmCIF file can contain multiple data blocks; typically, we access the first one
dataContainer = dataContainerList[0]
print(f"Data block ID: {dataContainer.getName()}")
# Access a specific data category, e.g., '_entity'
entity_category = dataContainer.getObj("entity")
if entity_category:
print(f"\nFound {entity_category.getRowCount()} entities:")
for i in range(entity_category.getRowCount()):
pdbx_description = entity_category.getValue("pdbx_description", i)
type_val = entity_category.getValue("type", i)
print(f" - Entity {i+1}: Type='{type_val}', Description='{pdbx_description}'")
else:
print("'_entity' category not found in the mmCIF file.")
else:
print(f"Failed to load data from {mmcif_url}. Please check the URL and network connection.")
Debug
Known issues
gotchaMultiple Python libraries exist for mmCIF parsing (e.g., `PDBeCIF`, `BioPython.PDB.MMCIFParser`, `mmcif-pdbx`, `python-modelcif`). Ensure you are explicitly using the `rcsb/py-mmcif` library (installed as `mmcif` via pip) as its API may differ from others.fixAlways import from `rcsb.utils.io` and related submodules for `mmcif` (PyPI package) to ensure you are using the correct library's API.
affects: All
breakingThe `rcsb/py-mmcif` project's internal versioning (e.g., `0.x.y` for GitHub commits) may not directly correspond to the PyPI `mmcif` package version. Historically, there have been updates to BinaryCIF handling (e.g., changing data item storage from tuples to lists) for compatibility, which could affect code relying on specific data types.fixPin your `mmcif` package version (`pip install mmcif==X.Y.Z`) and review the GitHub `HISTORY.txt` for `rcsb/py-mmcif` if encountering unexpected behavior, especially when working with BinaryCIF or migrating between older versions.
affects: <=0.84.0 (internal git versions before PyPI 1.1.0 equivalent)
deprecatedThe `mmcif-pdbx` library, while related, notes that versions after `0.*` break API compatibility by renaming methods to conform to PEP8. While `rcsb/py-mmcif` is the canonical library, users migrating from `mmcif-pdbx` may encounter API differences.fixIf migrating from `mmcif-pdbx`, consult the `rcsb/py-mmcif` documentation for equivalent API calls, as direct method name translations may not be possible.
affects: All versions of `mmcif-pdbx` > 0.* (if migrating to `mmcif`)
Upgrade
Version history
1.1.1latest on PyPI · released Apr 25, 2026
Audit
Dependencies
No dependency data recorded yet.