Install & Compatibility
Where this runs
tested against v2025.10.7 · 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 28.0s · import 0.956s · 562MB
601MB installed
● package 601MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Structure
✓ from pymatgen.core import Structure
Lattice
✓ from pymatgen.core import Lattice
Molecule
✓ from pymatgen.core import Molecule
MPRester
✓ from pymatgen.ext.matproj import MPRester
Vasprun
✓ from pymatgen.io.vasp import Vasprun
✗ from pymatgen.io.vasp.outputs import Vasprun
While 'outputs' submodule exists, the main 'Vasprun' object is typically imported directly from 'pymatgen.io.vasp'.
Kpoints
✓ from pymatgen.io.vasp.inputs import Kpoints
This quickstart demonstrates how to create a basic `Structure` object and interact with the Materials Project database using `MPRester`. An `MP_API_KEY` environment variable is required for `MPRester` functionality.
import os
from pymatgen.core import Structure, Lattice, Species
from pymatgen.ext.matproj import MPRester
# 1. Create a simple crystal structure (e.g., BCC iron)
lattice = Lattice.cubic(2.86)
species = [Species("Fe")]
coords = [[0, 0, 0]]
structure = Structure(lattice, species, coords)
print(f"Created structure: {structure.formula} with {structure.num_sites} sites.")
# 2. Use MPRester to fetch data (requires API key)
# Get your API key from materialsproject.org after logging in
# Set it as an environment variable 'MP_API_KEY'
api_key = os.environ.get("MP_API_KEY", "")
if api_key:
try:
with MPRester(api_key) as mpr:
# Fetch entries for a chemical system, e.g., Li-Fe-O
entries = mpr.get_entries("Li-Fe-O", inc_structure=True, property_data=["band_gap"])
print(f"Found {len(entries)} entries for Li-Fe-O.")
if entries:
first_entry = entries[0]
print(f"First entry formula: {first_entry.formula_pretty}")
if "band_gap" in first_entry.data:
print(f"Band gap: {first_entry.data['band_gap']} eV")
except Exception as e:
print(f"Error fetching data from Materials Project: {e}")
print("Ensure your MP_API_KEY is valid and has network access.")
else:
print("MP_API_KEY environment variable not found. Skipping MPRester example.")
pmg --version
Debug
Known issues
gotchaStarting with v2026.3.23, `pymatgen` underwent a major internal reorganization. Core functionality was moved to a separate `pymatgen-core` package, which `pymatgen` now depends on. While `pip install pymatgen` should remain fully backwards compatible and provide the same functionality, be aware of this architectural change in case of complex dependency management or introspection needs.fixNo user-facing fix is typically required, as 'pip install pymatgen' handles the new dependency. Advanced users may need to understand the new internal package structure.
affects: >=2026.3.23
gotchaThe `orjson` library became a required dependency as of v2025.5.28 for faster JSON handling. Ensure `orjson` is installed in your environment if you encounter import errors or unexpected behavior related to JSON serialization.fixEnsure `orjson` is installed: `pip install orjson`.
affects: >=2025.5.28
gotchaThe usage of `lxml` for `Vasprun` parsing fluctuated around v2025.5.1 and v2025.5.2. It was introduced for speed improvements, then removed shortly after for specific situations. This might lead to unexpected performance changes or dependency requirements depending on the exact `pymatgen` version you are using if `Vasprun` parsing is critical.fixCheck release notes for your specific version regarding `lxml` and `Vasprun` parsing. If performance is an issue, consider upgrading to the latest version which has optimized parsing without `lxml`.
affects: 2025.5.1 to 2025.5.2
gotchaThe behavior of `MPRester.get_entries` regarding `property_data` and `summary_data` was clarified and refined in v2025.4.24. `property_data` is now consistent with the returned entry, while `summary_data` (obtained via a kwarg) is more comprehensive but not always consistent. Users relying on specific data consistency may need to adjust their calls.fixReview calls to `MPRester.get_entries` and explicitly use `property_data` for consistent entry-specific information or `summary_data=True` for comprehensive (potentially less consistent) data.
affects: >=2025.4.24
deprecatedThe internal dependency for BibTeX parsing shifted from `pybtex` to `bibtexparser` in v2025.4.19. While `pymatgen` handles this change internally, users who were directly interacting with `pybtex`-related utilities within `pymatgen` might need to update their code.fixMigrate any direct usage of `pybtex` through `pymatgen` utilities to `bibtexparser` if issues arise. For most users, this change is internal and will not require code modification.
affects: >=2025.4.19
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pymatgen'
The 'pymatgen' library or one of its submodules is not installed in the active Python environment, or the environment is not correctly selected in the IDE.
fixInstall 'pymatgen' using pip or conda, and ensure the correct Python interpreter/environment is activated.
`pip install pymatgen` or `conda install -c conda-forge pymatgen`
AttributeError: 'Structure' object has no attribute 'specie'. Did you mean: 'species'?
Users are trying to access the 'specie' attribute (singular) on a 'Site' or 'Structure' object, but the correct attribute for element or species is 'species' (plural), which is more robust for disordered sites. The singular 'specie' property only works for ordered sites and its use is discouraged.
fixUse `site.species` instead of `site.specie`.
`# Wrong: site.specie.name`
`# Correct: site.species.name`
ImportError: Spglib required. Please either run python setup.py install for pymatgen, or install pyspglib from spglib.
The 'spglib' library, which 'pymatgen' uses for space group analysis, is a required dependency but is not properly installed or accessible in the Python environment.
fixInstall 'spglib' (often as 'pyspglib' or 'spglib' directly) separately, or ensure 'pymatgen' is installed in a way that handles its dependencies correctly (e.g., via `conda`).
`pip install spglib` or `conda install -c conda-forge spglib`
ValueError: numpy.ndarray size changed, may indicate binary incompatibility. Expected X from C header, got Y from PyObject.
This error typically arises from an incompatibility between the installed 'numpy' version and other compiled packages (like 'pymatgen' or its underlying C extensions) that were built against a different 'numpy' API. This is common after 'numpy' updates.
fixReinstall 'numpy' and 'pymatgen' (and potentially other scientific libraries) to ensure they are built against compatible 'numpy' versions.
`pip install --force-reinstall numpy pymatgen`
Upgrade
Version history
2026.5.4latest on PyPI · released May 4, 2026
Audit
Dependencies
orjsonrequiredUsed as the default JSON handler for faster serialization/deserialization.
matcalcoptionalRequired for computing advanced properties like elasticity, EOS, and phonons using Structure.calc_property.