Registry / database / mp-api

mp-api

JSON →
library0.46.3pypypi✓ verified 85d ago

mp-api is the official Python client for the Materials Project API, providing programmatic access to the vast Materials Project database. It features the MPRester class for easy data retrieval and is actively maintained with frequent updates to align with the evolving API and new data methodologies.

databasedata
pip install mp-api
package ↗
INSTALL
IMPORT
SIG · MP-API
M
mp-api
databasepythonv0.46.3
Install
36.8s avg
Import
15005ms
Disk
831MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.45.13 · 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
py 3.10–3.920 runs
build_error
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 36.8s · import 9.003s · 621MB
831MB installed
● package 831MB
Code
Verified usage

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

MPRester
✓ from mp_api.client import MPRester
✗ from pymatgen.matproj.rest import MPRester
The `mp-api` client replaces the legacy MPRester previously found in `pymatgen`. Users should migrate to the new import path for current functionality.

This quickstart demonstrates how to instantiate the `MPRester` client using an API key from an environment variable and retrieve basic summary information for a material. You need a Materials Project API key, obtainable from your profile dashboard, to run this example.

import os from mp_api.client import MPRester # Set your Materials Project API key as an environment variable # Example: export MP_API_KEY="YOUR_API_KEY_HERE" # You can find your API key on your Materials Project profile dashboard. api_key = os.environ.get('MP_API_KEY', '') if not api_key: print("Error: MP_API_KEY environment variable not set. Please set it to your Materials Project API key.") else: try: with MPRester(api_key) as mpr: # Fetch summary data for silicon (material_id: mp-149) material_id = "mp-149" docs = mpr.materials.summary.search(material_ids=[material_id]) if docs: print(f"Material ID: {docs[0].material_id}") print(f"Formula: {docs[0].formula_pretty}") print(f"Band gap: {docs[0].band_gap} eV") else: print(f"No data found for material ID: {material_id}") except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
breakingThe `mp-api` library is the successor to the legacy `MPRester` client previously embedded in `pymatgen`. Users of the old `pymatgen.matproj.rest.MPRester` should migrate to `from mp_api.client import MPRester` to access the latest API features and maintain compatibility.
fix
Update your import statements and client instantiation to use `from mp_api.client import MPRester`. Ensure `mp-api` is installed and updated.
affects: <0.30.5 (for `mp-api` integration requirements with `mpcontribs-client`), N/A (for `pymatgen`'s legacy API)
gotchaAn API key is mandatory for using the Materials Project API client. Failing to provide a valid key, either as a direct argument to `MPRester` or via the `MP_API_KEY` environment variable, will result in authentication errors.
fix
Obtain your API key from your Materials Project profile dashboard and set it as the `MP_API_KEY` environment variable or pass it directly to `MPRester("YOUR_API_KEY")`.
affects: All versions
gotchaFor heavy or high-volume API usage, it is recommended to notify the Materials Project team by emailing `heavy.api.use@materialsproject.org`. This helps them anticipate server load and can prevent potential rate-limiting or service interruptions.
fix
Contact the Materials Project team if your API usage is expected to be extensive.
affects: All versions
gotchaThe Materials Project API and its underlying data models (`emmet-core`) are continuously evolving. While the `mp-api` client is designed to abstract away many changes, occasional discrepancies or unexpected behavior can arise, especially if comparing with direct REST API calls or when using older versions of related data model libraries.
fix
Keep `mp-api` and related packages (e.g., `emmet-core` if used directly) updated. Consult the official Materials Project documentation and community forums for the latest updates and known issues.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mp_api'
The `mp-api` package is not installed in the active Python environment or the environment where it's installed is not correctly activated, especially in IDEs like Jupyter notebooks.
fix
Install the package using pip: `pip install mp-api`. If using an IDE or virtual environment, ensure the correct Python interpreter where `mp-api` is installed is selected.
MPRestError: REST query returned with error status code 401 on URL... with message: No API key found in request
The Materials Project API key is either missing, incorrect, expired, or a legacy API key is being used with the new `mp-api` client. It might also be incorrectly set as an environment variable or passed to `MPRester`.
fix
Obtain your API key from the new Materials Project dashboard (next-gen.materialsproject.org/api) and either pass it directly to `MPRester(api_key="YOUR_API_KEY")` or set it as an environment variable named `MP_API_KEY`.
AttributeError: 'NoneType' object has no attribute 'get'
An `mp-api` call (e.g., a search method) returned `None` because no data was found for the given query, or there was a temporary backend issue, and the subsequent code attempted to access an attribute or element of this `None` object. This can also be caused by specific dependency version mismatches.
fix
Implement explicit checks for `None` before attempting to process results (e.g., `if result: ... else: handle_no_data()`). Ensure `mp-api` and its core dependencies like `emmet-core` are updated or compatible.
TypeError: SeparationPlane.init() got an unexpected keyword argument 'point_groups_permutations'
This error typically indicates an incompatibility between `mp-api` and its underlying dependencies, such as `pymatgen` or `emmet-core`, where a method signature has changed. Similar issues arise with `PydanticImportError` due to Pydantic v1 vs v2 conflicts.
fix
Update `mp-api` and its core dependencies (`pymatgen`, `emmet-core`, `pydantic`, `pydantic-settings`) to their latest compatible versions using `pip install --upgrade mp-api pymatgen emmet-core pydantic pydantic-settings`. If a specific dependency version is known to be problematic, consider pinning it (e.g., `pip install emmet-core==0.83.0` for older issues or `pip install 'pydantic<2'` for Pydantic v1 compatibility).
Upgrade
Version history
0.46.3latest on PyPI · released Jun 10, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
12 hits · last 30 days
node
12
Resources
packagehttps://pypi.org/project/mp-api/ ↗
mp-api — pip install mp-api · libregistry