Installation

Install MLIP Arena via PyPI or from source with all pretrained models.

Requirements

MLIP Arena requires Python 3.9 or later (3.10, 3.11, and 3.12 are fully tested).

PyPI (simple)

Install from PyPI

The PyPI package installs the Prefect workflow framework and all task definitions. It does not bundle pretrained model weights — you can still bring your own ASE-compatible calculator.

pip install mlip-arena

This install is sufficient to run workflows with any custom ASE Calculator and to orchestrate tasks with Prefect. To use the integrated pretrained models (MACE, CHGNet, eSEN, etc.) you need the source installation below.

Source (recommended)

Install from source

The source installation clones the repository and uses uv to install all compiled pretrained models with minimal dependency conflicts.

We strongly recommend a clean virtual environment before proceeding. Multiple popular MLIPs have conflicting transitive dependencies; installing into an existing environment is likely to break things.

1. Install uv (optional but strongly recommended)

   uv is a fast Python package manager that dramatically reduces install time and resolves conflicts better than pip.

   curl -LsSf https://astral.sh/uv/install.sh | sh
   source $HOME/.local/bin/env
   
2. Clone the repository

   git clone https://github.com/atomind-ai/mlip-arena.git
   cd mlip-arena
   
3. Run the one-shot install script

   Choose the script for your operating system:

   Linux (GPU / CUDA 12.4)

   # Targets PyTorch 2.4 + CUDA 12.4
   bash scripts/install.sh
   

   The scripts pin compatible versions of torch, torch-scatter, torch-sparse, and dgl, then install every optional model extra:

   Linux — scripts/install.sh

   TORCH=2.4
   CUDA=cu124
   uv pip install torch==${TORCH}.0
   uv pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-${TORCH}.0+${CUDA}.html
   uv pip install dgl -f https://data.dgl.ai/wheels/torch-${TORCH}/${CUDA}/repo.html
   uv pip install mlip-arena[fairchem]
   uv pip install mlip-arena[orb]
   uv pip install mlip-arena[matgl]
   uv pip install mlip-arena[test]
   uv pip install mlip-arena[mace]
   

   If disk space is tight, installing all compiled models can fill up local storage quickly. Pass --no-cache to uv pip install or run uv cache clean afterwards to reclaim space.

---

Optional model extras

You can install support for individual model families instead of running the full install script. Each extra pins the version tested in MLIP Arena:

Extra	Package pinned	Models unlocked
mace	mace-torch==0.3.12	MACE-MP(M), MACE-MPA, MACE-OFF(M)
matgl	matgl==1.2.6	M3GNet, CHGNet (via matgl)
fairchem	fairchem-core==1.10.0	eqV2(OMat), eSEN, EquiformerV2, eSCN
orb	orb-models==0.4.0	ORB, ORBv2
deepmd	deepmd-kit@git (v3.0.0b4)	DeepMD

# Install a single extra, e.g. MACE only
pip install "mlip-arena[mace]"

# Install multiple extras at once
pip install "mlip-arena[mace,matgl,fairchem]"

The deepmd extra pins torch==2.2.0 and installs deepmd-kit directly from GitHub. Install it in isolation to avoid overwriting the PyTorch version required by other models.

---

HuggingFace authentication (fairchem OMat24)

The eqV2(OMat) and eSEN checkpoints are gated behind a HuggingFace model repository. You must:

1. Request access

   Visit the facebook/OMAT24 model repo on HuggingFace and request downloading access. Note: you need access to the model repo, not the dataset repo.

2. Authenticate locally

   Log in to HuggingFace Hub on your machine:

   huggingface-cli login
   

   This writes a token to ~/.cache/huggingface/token. The fairchem loader will pick it up automatically at import time.

Skipping authentication will cause the fairchem models to fail at checkpoint download with a 401 Unauthorized error even after a successful pip install mlip-arena[fairchem].

---

Virtual environment recommendations

Because MLIP Arena integrates many models with conflicting dependencies, always install into a dedicated virtual environment.

uv venv (recommended)

uv venv .venv --python 3.11
source .venv/bin/activate

uv venv is the fastest option and pairs naturally with uv pip install used in the install scripts.