Install & Compatibility
Where this runs
tested against v2026.5.18 · 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
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✓ 26.6s
py 3.12
✕ build_error
✓ 28.3s
py 3.13
✕ build_error
✓ 29.1s
py 3.9
✕ build_error
✕ build_error
624MB installed
● package 624MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Structure
✓ from pymatgen.core import Structure
✗ from pymatgen import Structure
In pymatgen-core, core classes are under pymatgen.core, not top-level pymatgen.
Molecule
✓ from pymatgen.core import Molecule
✗ from pymatgen import Molecule
Same as Structure; Molecule moved to pymatgen.core.
Lattice
✓ from pymatgen.core import Lattice
✗ from pymatgen import Lattice
Lattice is also in pymatgen.core.
Element
✓ from pymatgen.core import Element
✗ from pymatgen import Element
Element moved to pymatgen.core.
Create a silicon diamond cubic structure using pymatgen-core. Note: import from pymatgen.core, not pymatgen directly.
from pymatgen.core import Structure, Lattice, Element
# Create a simple silicon diamond cubic structure
lattice = Lattice.cubic(5.431) # lattice constant in Angstrom
species = [Element("Si")] * 8
coords = [
[0, 0, 0],
[0.25, 0.25, 0.25],
[0.5, 0.5, 0],
[0.5, 0, 0.5],
[0, 0.5, 0.5],
[0.75, 0.75, 0.25],
[0.75, 0.25, 0.75],
[0.25, 0.75, 0.75]
]
structure = Structure(lattice, species, coords, coords_are_cartesian=False)
print(structure)
print(f"Volume: {structure.volume:.2f} ų")
Debug
Known issues
breakingpymatgen-core is a refactored subset of pymatgen. Many modules (e.g., analysis, io.vasp, electronic_structure) are not included; they remain in the full pymatgen package. Code that imports from pymatgen.core will break if it expects all functionality of pymatgen.fixInstall pymatgen (the full package) if you need advanced features. Use pymatgen-core only for core data structures and basic I/O. Adjust imports to use pymatgen.core subpackage.
affects: all versions of pymatgen-core
gotchaSome classes that were previously at the top-level pymatgen (e.g., Structure, Molecule) are now inside pymatgen.core. Direct imports from pymatgen will fail with ImportError or AttributeError.fixChange 'from pymatgen import Structure' to 'from pymatgen.core import Structure'.
affects: >=2026.2.24
deprecatedThe original pymatgen package may eventually be superseded by pymatgen-core. Users should monitor migration guides for future breaking changes.fixStay updated with release notes. Consider using pymatgen-core for new projects if you only need core features.
affects: pymatgen-core >=2026.2.24
Errors
Common errors & fixes
ImportError: cannot import name 'Structure' from 'pymatgen' (unknown location)
pymatgen-core moved core classes to pymatgen.core subpackage.
fixUse 'from pymatgen.core import Structure' instead.
ModuleNotFoundError: No module named 'pymatgen.io.vasp'
VASP I/O is not part of pymatgen-core; it's in the full pymatgen package.
fixInstall pymatgen (the full package) via 'pip install pymatgen' and import from 'pymatgen.io.vasp'.
AttributeError: 'Structure' object has no attribute 'get_sorted_structure'
Some methods may not be available in pymatgen-core if they were moved to other modules.
fixCheck the pymatgen-core documentation for available methods. Use pymatgen (full) if the method is missing.
Upgrade
Version history
2026.5.18latest on PyPI · released May 18, 2026
Audit
Dependencies
pymatgenoptionalFull pymatgen package may be needed for advanced features not yet migrated (e.g., some analysis tools). pymatgen-core is a subset.