Installation¶
ChemGraph requires Python 3.11 or newer. Use a virtual environment because its scientific dependencies may conflict with packages in other projects.
Install the command-line application¶
With uv, one command installs ChemGraph
in its own environment and exposes the chemgraph command:
If uv reports that its executable directory is missing from PATH, run
uv tool update-shell and restart your shell. Upgrade with uv tool upgrade chemgraph.
To add optional extras to the tool environment, reinstall with the extras you
need, for example uv tool install "chemgraph[rag,docking]". A tool install
cannot be imported from your own Python interpreter or notebook; for that, use
a virtual environment as described below.
Install for Python and notebooks¶
We recommend uv to create the virtual environment and install ChemGraph:
Or with standard venv and pip:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install chemgraph
Confirm that the command-line entry point and model registry load:
The core installation includes the agent framework, ASE, RDKit, MACE, EMT, the Streamlit dependencies, and the general MCP server. MACE downloads model weights when first used; start with EMT if you need an offline calculator smoke test.
Install from source¶
Use a source checkout for the Streamlit interface, examples, documentation, or development:
git clone https://github.com/argonne-lcf/ChemGraph.git
cd ChemGraph
uv venv .venv
source .venv/bin/activate
uv pip install -e .
Or with standard venv and pip:
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
Optional extras¶
For a Python or source environment, install only the integrations your workflow
needs, in the active environment.
The commands below use uv pip; with standard venv/pip or conda, replace
uv pip with python -m pip.
| Extra | Install command | Adds |
|---|---|---|
calculators |
uv pip install "chemgraph[calculators]" |
TBLite |
uma |
uv pip install "chemgraph[uma]" |
UMA through fairchem-core |
ui |
uv pip install "chemgraph[ui]" |
Additional UI dependencies |
rag |
uv pip install "chemgraph[rag]" |
Document ingestion and vector stores |
xanes |
uv pip install "chemgraph[xanes]" |
XANES workflow dependencies |
docking |
uv pip install "chemgraph[docking]" |
Meeko docking preparation |
parsl |
uv pip install "chemgraph[parsl]" |
Parsl execution |
ensemble_launcher |
uv pip install "chemgraph[ensemble_launcher]" |
ALCF ensemble launcher |
globus_compute |
uv pip install "chemgraph[globus_compute]" |
Globus Compute execution |
globus |
uv pip install "chemgraph[globus]" |
Globus CLI for transfers and readiness checks |
academy |
uv pip install "chemgraph[academy]" |
Academy multi-agent runtime |
codex |
Source checkout: uv pip install -e ".[codex]" |
Codex subscription route |
Extras can be combined:
UMA environment
UMA's e3nn requirements can conflict with the MACE stack in the core
environment. A separate virtual environment is the safest setup for UMA.
External programs¶
Some integrations are Python adapters, not bundled simulation programs:
- ORCA and NWChem must be installed and configured for ASE separately.
- FDMNES is required for local XANES execution; set
FDMNES_EXE. - AutoDock Vina is normally installed from conda-forge for docking.
- Site-specific gRASPA and HPC modules require executables, schedulers, and filesystem paths available at the target facility.
Conda environments¶
If an integration needs compiled or external dependencies, create a clean environment first and install ChemGraph with pip inside it:
Docker¶
Docker avoids a local Python installation and provides CLI, Streamlit, MCP, and Jupyter-oriented images. See Docker for commands, ports, credential forwarding, and artifact volumes.
Next step¶
Continue with the quickstart, then configure a provider in Models and authentication.