gemmi

library0.7.5pypypi✓ verified 23d ago

Gemmi is a C++ library with comprehensive Python bindings designed for structural biology, particularly macromolecular crystallography. It provides tools for working with various file formats like mmCIF, PDB, MTZ, MRC/CCP4, and general CIF/STAR files, handling macromolecular models, refinement restraints, reflection data, and crystallographic symmetry. Currently at version 0.7.5, it is an actively developed open-source project maintained by CCP4 and Global Phasing Ltd.

data ai-ml

pip install gemmi

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GEMMI

gemmi

datapythonv0.7.5

Install

1.7s avg

Import

28ms

Disk

23MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.7.5 · 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

musl

glibc

py 3.10

✕ build_error

✓ 1.7s

py 3.11

✓ —

✓ 1.8s

py 3.12

✓ —

✓ 1.6s

py 3.13

✓ —

✓ 1.6s

py 3.9

✕ build_error

✓ 2s

23MB installed

● package 23MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

gemmi

✓ import gemmi

Structure

✓ import gemmi structure = gemmi.read_pdb('file.pdb')

This quickstart demonstrates how to load a PDB file using `gemmi.read_file()` and access basic structural elements like models, chains, residues, and atoms. It creates a dummy PDB file for a self-contained, runnable example.

import gemmi import os # Create a dummy PDB file for demonstration pdb_content = """ ATOM 1 N ALA A 1 29.186 15.021 19.530 1.00 19.34 N ATOM 2 CA ALA A 1 28.710 16.299 19.988 1.00 18.23 C ATOM 3 C ALA A 1 27.241 16.353 20.306 1.00 17.51 C ATOM 4 O ALA A 1 26.702 17.433 20.370 1.00 18.00 O ATOM 5 CB ALA A 1 29.417 17.309 19.066 1.00 20.00 C TER """ with open("test.pdb", "w") as f: f.write(pdb_content) # Load the PDB file doc = gemmi.read_file("test.pdb") # Access components of the structure model = doc.models[0] chain = model.chains[0] residue = chain.residues[0] print(f"File contains {len(doc.models)} model(s).") print(f"First model has {len(model.chains)} chain(s).") print(f"First chain has {len(chain.residues)} residue(s).") print(f"First residue is {residue.name} {residue.seqid.num} and has {len(residue.atoms)} atoms.") # Clean up the dummy file os.remove("test.pdb")

gemmi --version

Debug

Known issues

breakingGemmi 0.7+ migrated its Python bindings from pybind11 to nanobind. This is a significant change that may break compatibility for users who were previously interacting with the C++ library at a lower level or had custom extensions built against pybind11. Expect internal API changes related to the binding mechanism.

fix

Review your code for any direct interactions with the binding layer or custom C++ extensions. Recompile any custom extensions using nanobind or the latest Gemmi build system. Primarily affects advanced users and developers of Gemmi extensions.

affects: >=0.7.0

breakingThe behavior of `gemmi.Op` parsing (specifically `parse_triplet("h,k,l")` versus `parse_triplet("x,y,z")`) changed in Gemmi 0.7 to align with `cctbx` and `Pointless` conventions. This affects how crystallographic symmetry operations are interpreted and stored.

fix

Carefully review any code dealing with crystallographic symmetry operations and `Op` parsing. Explicitly specify the notation kind if ambiguities arise or adapt code to the new consistent behavior.

affects: >=0.7.0

breakingSeveral functions have been deprecated and subsequently removed in Gemmi 0.7+. Notable examples include `UnitCell.fractionalization_matrix` and `UnitCell.orthogonalization_matrix`, which should now be accessed via `frac.mat` and `orth.mat` respectively. `count_hydrogen_sites()` has also been removed, with `has_hydrogen()` as its replacement.

fix

Update your code to use the new method names. For `UnitCell` matrices, use `unit_cell.frac.mat` and `unit_cell.orth.mat`. For hydrogen site counting, use `residue.has_hydrogen()` or similar atom-level checks.

affects: >=0.7.0

gotchaThe Python API documentation on `gemmi.readthedocs.io/en/latest/` has not been updated since Gemmi 0.6.7 due to the migration to nanobind. It is currently outdated and may not reflect the latest API changes or available functions in versions 0.7 and newer.

fix

Refer to the main Gemmi documentation (typically the overview and installation sections) or the project's GitHub repository for the most up-to-date information and examples. Use the search box on the main documentation site.

affects: >=0.7.0

gotchaThere are two distinct packages: `gemmi` (the Python extension module) and `gemmi-program` (the command-line executable). Users sometimes confuse them or install the wrong one expecting the other's functionality.

fix

Ensure you `pip install gemmi` for the Python library and its bindings. If you need the standalone command-line tools, install `gemmi-program`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'gemmi'

The 'gemmi' Python package is not installed in the current Python environment.

fix

Install the package using pip: `pip install gemmi`

ValueError: not an integer (when reading mmCIF files with gemmi.read_structure())

This error occurs when `gemmi`'s `read_structure()` function encounters unexpected non-integer data where an integer is expected within an mmCIF file, often due to malformed or unconventional formatting in specific data fields.

fix

Check the mmCIF file for parsing errors or unconventional data. If the file is valid but causes issues, consider reporting it to the `gemmi` developers or trying to pre-process the file to fix problematic entries if feasible. This was often a bug in older gemmi versions fixed in newer ones.

AttributeError: 'Structure' object has no attribute '...' (e.g., when accessing subchain or entity data)

This typically happens when attempting to access attributes or properties on a `gemmi.Structure` object that have not been properly initialized or set up, often because the `setup_entities()` method was not called after reading the structure.

fix

After reading a structure (e.g., `st = gemmi.read_structure(path)`), call `st.setup_entities()` to populate entities and subchains, which are often required for further structural analysis.

Upgrade

Version history

0.7.5latest on PyPI · released Mar 2, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/project-gemmi/gemmi ↗

packagehttps://pypi.org/project/gemmi/ ↗

homepagehttps://gemmi.github.io/ ↗