Install & Compatibility
Where this runs
tested against v0.85.1 · 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
✓ 45.85s
py 3.11
✕ build_error
✓ 46.7s
py 3.12
✕ build_error
✓ 40.83s
py 3.13
✕ build_error
✓ 41s
py 3.9
✕ build_error
6/8 runs
778MB installed
● package 778MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FastAPI
✓ from fastapi import FastAPI
emmet-api is built on FastAPI, so many core FastAPI components are imported directly.
build_router
✓ from emmet_api.routes import build_router
This function is used to integrate Emmet's predefined API routes into a FastAPI application.
EmmetSettings
✓ from emmet_api.core.config import EmmetSettings
Used for loading application-specific configurations, such as database connection details.
The `emmet-api` library primarily provides an API server, built on FastAPI. The quickstart demonstrates how to set up a basic FastAPI application and integrate Emmet's routers. To run the API server, you would typically use the `uvicorn` command, pointing to the configured FastAPI application instance, whether it's a custom script or the default `emmet_api.main:app` entry point provided by the package. Ensure necessary environment variables for `EmmetSettings` (e.g., database connection) are configured.
import uvicorn
from fastapi import FastAPI
from emmet_api.routes import build_router
from emmet_api.core.config import EmmetSettings
# Initialize FastAPI app
app = FastAPI(
title="Emmet API Server Example",
description="Minimal Emmet API instance for demonstration",
version="0.86.3"
)
# Load settings (adjust as per your environment variables or config files)
settings = EmmetSettings() # This will load settings from environment variables or .env file
# Build and include routers into the FastAPI app
# The build_router function modifies the app in-place.
build_router(app, settings)
# To run this application, save it as, e.g., `my_api.py` and execute:
# uvicorn my_api:app --host 0.0.0.0 --port 8000 --reload
# Alternatively, if running directly from the installed emmet-api package's entry point:
# uvicorn emmet_api.main:app --host 0.0.0.0 --port 8000 --reload
# The following lines are for demonstration if this script were the entry point
# if __name__ == "__main__":
# uvicorn.run(app, host="0.0.0.0", port=8000)
# Note: This quickstart primarily shows the Python setup.
# Running the server typically involves the `uvicorn` command-line tool.
Debug
Known issues
breakingThe Emmet project is under active development with frequent pre-release versions (e.g., `0.87.0.devX`). While `emmet-api` has stable releases, significant architectural and API changes are common across the broader Emmet ecosystem, which may lead to breaking changes in minor versions or impact integration with other Emmet packages.fixRefer to the GitHub changelog and release notes for each specific version before upgrading, especially pre-releases. Pin dependencies to exact versions to avoid unexpected breakage.
affects: 0.87.0.devX and potentially future minor stable releases
gotchaWhile `emmet-api` is a standalone PyPI package, it is part of a larger 'Emmet toolkit' from the Materials Project. Full functionality and understanding of the data models often require interaction with or knowledge of `emmet-core`. Users might need to install `emmet-core` separately to access core document definitions and utilities.fixFamiliarize yourself with the `emmet-core` library and install it if you need to work directly with Materials Project data models or schema definitions: `pip install emmet-core`.
affects: All versions
gotchaThe `emmet-api` package explicitly requires Python >=3.11. Attempting to install or run it with older Python versions will result in installation failures or runtime errors.fixEnsure your Python environment is at version 3.11 or newer. Use tools like `pyenv` or `conda` to manage multiple Python versions if needed.
affects: <0.86.3
Errors
Common errors & fixes
The `emmet-api` package explicitly requires Python >=3.11. Attempting to install or run it with older Python versions will result in installation failures or runtime errors.
The `emmet-api` library is built for Python 3.11 and newer, and will not function correctly with older Python versions.
fixEnsure your Python environment is at version 3.11 or newer. You can manage multiple Python versions using tools like `pyenv` or `conda`.
ModuleNotFoundError: No module named 'emmet.core'
Although `emmet-api` is a standalone package, many core functionalities, especially those dealing with Materials Project data models and schema definitions, rely on `emmet-core`. This error indicates `emmet-core` is not installed or accessible.
fixInstall the `emmet-core` package: `pip install emmet-core`
ImportError: cannot import name 'SomeEmmetCoreClass' from 'emmet.core.some_module'
This error often occurs when there are version mismatches or breaking changes within the `emmet-core` library or its dependent packages like `pymatgen` and `mp-api`. Specific classes might have been moved, renamed, or removed in newer versions of `emmet-core` that a different version of a dependent library is trying to import.
fixUpdate `emmet-core` to the latest compatible version with your `mp-api` and `pymatgen` installations. If the issue persists, carefully check the release notes and changelogs for `emmet-api`, `emmet-core`, `mp-api`, and `pymatgen` for breaking changes related to the imported class and pin dependencies to exact working versions.
HTTP 401 Unauthorized
This error indicates a failure in authenticating with the Emmet API server, typically due to a missing, incorrect, or expired API key or token when making a request.
fixVerify that your API key or token is correctly configured and has the necessary permissions. Ensure it is passed in the request headers (e.g., `Authorization: Bearer YOUR_API_KEY`) as required by the API server.
AttributeError: 'SomeEmmetObject' object has no attribute 'some_attribute'
This is a common Python error that occurs when you try to access an attribute or method on an object that does not possess it. This can happen in `emmet-api` if the underlying data models or API responses have changed, or if you are attempting to access an attribute that was never part of the object.
fixRefer to the `emmet-api` documentation or the source code for the specific object (`SomeEmmetObject`) to confirm the available attributes. If you recently updated the library, check the changelog for breaking changes related to object structures or attribute names.
Upgrade
Version history
0.87.0latest on PyPI · released Jun 8, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.11 or newer.
emmet-corerequiredProvides core data models and definitions used by the API. While not a direct PyPI dependency of emmet-api, it's fundamental to the Emmet ecosystem.