Install & Compatibility
Where this runs
tested against v? · pip install
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.910 runs
build_error
glibcpy 3.10–3.910 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TaskDoc
✓ from emmet.core.tasks import TaskDoc
MaterialsBuilder
✓ from emmet.builders.materials.materials import MaterialsBuilder
MPRester
✓ from pymatgen.ext.matproj import MPRester
MPRester is from pymatgen, but it is the primary and recommended way for users to interact with Emmet-structured data from the Materials Project API.
This quickstart demonstrates how to fetch materials data, specifically a TaskDoc, from the Materials Project database. Emmet defines the underlying schema for these documents. The `MPRester` from `pymatgen` is the standard client for interacting with the Materials Project API, which serves Emmet-structured data. Ensure your `MP_API_KEY` environment variable is set for successful API calls.
import os
from pymatgen.ext.matproj import MPRester
# Set your Materials Project API key as an environment variable (MP_API_KEY)
# Get your API key from https://materialsproject.org/dashboard
api_key = os.environ.get("MP_API_KEY", "")
if not api_key:
print("Warning: MP_API_KEY environment variable not set. API calls will likely fail.")
print("Using a placeholder API key for demonstration purposes.")
api_key = "YOUR_API_KEY_HERE_IF_NOT_SET_IN_ENV"
try:
with MPRester(api_key=api_key) as mpr:
# Fetch the TaskDoc for a specific Materials Project task_id
# Example Task ID for LiCoO2 calculation
task_id = "mp-149"
task_doc = mpr.get_task_doc(task_id)
print(f"\nSuccessfully fetched TaskDoc for ID: {task_id}")
print(f"Pretty Formula: {task_doc.formula_pretty}")
print(f"Energy per atom: {task_doc.energy_per_atom:.3f} eV/atom")
except Exception as e:
print(f"\nAn error occurred during data retrieval: {e}")
print("Please ensure your MP_API_KEY is correctly set and valid.")
Debug
Known issues
breakingThe official package name for the Materials Project's Emmet library on PyPI is `mp-emmet`, not `emmet`. Installing `emmet` will fetch an old, unrelated package (version 2018.6.7) that does not correspond to the current Materials Project framework. Always use `pip install mp-emmet` to get the correct library.fixUninstall the old package (`pip uninstall emmet`) and install the correct one (`pip install mp-emmet`).
affects: All versions
gotchaEmmet relies heavily on `pydantic` for defining data schemas. Incompatible versions of `pydantic` (e.g., v1 vs v2) can lead to `ValidationError` or unexpected behavior. Check Emmet's `install_requires` for the specific `pydantic` version range.fixEnsure `pydantic` version is compatible with `mp-emmet`'s requirements. Consider using a virtual environment or `pip install 'mp-emmet[full]'` to install a complete set of compatible dependencies.
affects: All versions
gotchaThe Emmet project is under active development, and API methods or document schemas can change between minor releases, especially in `emmet.core` definitions. Always refer to the official documentation for the specific version you are using to avoid unexpected behavior.fixConsult the changelog or official documentation at `mp-emmet.materialsproject.org` before upgrading and adapt your code as necessary.
affects: All versions, particularly between minor updates (e.x. 2024.5.17 to 2024.6.x)
gotchaInteracting with the Materials Project database via `MPRester` requires an API key. This key must be obtained from the Materials Project website and typically set as the `MP_API_KEY` environment variable. Without it, API calls will fail.fixObtain an API key from `materialsproject.org/dashboard` and set it as an environment variable: `export MP_API_KEY="YOUR_KEY_HERE"` or pass it directly to the `MPRester` constructor: `MPRester(api_key="YOUR_KEY")`.
affects: All versions using MPRester
Audit
Dependencies
pymongorequiredDatabase interaction with MongoDB for storing and retrieving Emmet documents.
pydanticrequiredData validation and settings management, essential for Emmet's schema definitions.
montyrequiredMaterials Project's common utilities for scientific data objects and general helpers.
Resources
No resource links recorded.