Skip to content

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:

uv tool install chemgraph

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:

uv venv .venv
source .venv/bin/activate              # Windows: .venv\Scripts\activate
uv pip 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:

chemgraph --help
chemgraph models

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:

uv pip install "chemgraph[academy,parsl,globus_compute]"

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:

conda create -n chemgraph python=3.11
conda activate chemgraph
python -m pip install chemgraph

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.