Installation¶
mliport does not live in one big environment. Each backend (MACE, DPA, GRACE,
UMA, and the opt-in NEP) pulls in its own stack, and those stacks do not always get
along, so the installer builds one environment per backend and installs
mliport into each. The mliport you run from .venv-mace can only run MACE;
the one in .venv can only run UMA, and so on. Pick the backends you need,
install those, and call mliport from the matching environment.
The installer¶
Install uv and clone the repository:
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/hydrogen1222/mliport
cd mliport
On a machine with an NVIDIA GPU and a working driver (this route was tested on a V100-SXM2-16GB with driver 580.173.02):
On a machine without one:
NEP is opt-in: it is not in the default engine list, because its native runtime
also needs a gpumd binary that you build yourself (see
NEP). Add it explicitly:
./scripts/install_mliport.sh --engines nep --device cpu # CPU ASE runtime (Calorine CPUNEP)
./scripts/install_mliport.sh --engines nep --device auto # GPU machine; the closing doctor needs your gpumd build
Like every other backend, .venv-nep gets the pinned calorine and an editable
mliport in one resolver run, so .venv-nep/bin/mliport exists and doctor can
run. The installer does not compile gpumd. With --device cpu the install
needs no gpumd: the CPU ASE runtime works immediately. With --device cuda, or
--device auto on a machine with an NVIDIA GPU, the closing doctor checks the
CUDA path and fails naming gpumd until one is on PATH or in
MLIPORT_GPUMD_COMMAND. The environment is already installed by then, but the
bin/mliport-nep launcher is only written after every step succeeds, so either
build gpumd and re-run the installer, or install with --device cpu /
--skip-doctor (and call .venv-nep/bin/mliport directly in the meantime).
Re-running the installer while an environment already exists is decided by an
explicit contract before any step runs. A compatible environment — a real
virtual environment of the requested Python that carries no other backend's
packages — is reused and its pinned packages are re-resolved in place. Anything
else is refused: a plain directory at that path, an interpreter that cannot
report its version, a venv built with another Python, or a venv that already
holds another backend's framework (for example torch inside .venv-nep).
The refusal names the reason, changes nothing, and tells you to add --clean,
which deletes and rebuilds only the environments of the engines you name. Pass fewer engines if you only need some. --dry-run prints every step without
executing anything. Unless you give --skip-doctor, the installer runs
mliport doctor in each environment when it finishes. The analysis, transport
and electrolyte features come with the same install; there is no second step.
The installer also writes small launchers into ./bin/:
./bin/mliport-mace sp structure.cif --model model.model --model-type mace
./bin/mliport-uma sp structure.cif --model uma.pt --model-type uma
A launcher only picks the Python environment. It never sets a model, a dtype or any scientific option for you.
Which environment runs what¶
| Backend | Environment | Python | Runtime stack |
|---|---|---|---|
| UMA (FAIRChem) | .venv |
3.11, 3.12, 3.13 | fairchem-core==2.25.0 (torch 2.13.0) |
| MACE | .venv-mace |
3.10, 3.11, 3.12, 3.13 | mace-torch==0.3.16 (torch 2.8.0) |
| DPA (DeepMD-kit) | .venv-dpa |
3.10, 3.11, 3.12, 3.13 | deepmd-kit @ git+https://github.com/deepmodeling/deepmd-kit.git@0edeaef5617e9878edeb2346bf37bb6a035a4f51 (torch 2.11.0) |
| NEP (Calorine / GPUMD) | .venv-nep |
3.10, 3.11, 3.12, 3.13 | calorine==4.1 (NumPy/ASE, resolved by the installer; gpumd built with CUDA Toolkit 12.9) |
| GRACE | .venv-grace |
3.10, 3.11, 3.12, 3.13 | tensorpotential==0.6.0 (tensorflow 2.20.0) |
For NEP the parenthesis names two different things: Calorine runs on NumPy and
ASE, which the installer resolves together with mliport (neither is pinned
separately), while CUDA Toolkit 12.9 is the toolkit the separately built
gpumd binary was verified with. They are not one version.
The Python column is what the installer will accept for that backend: the
intersection of the Python versions mliport supports, the backend's own
requires-python, and the Python range of the framework wheels it needs. The
table is generated from the compatibility registry
(mliport/mliport/install/compatibility.py), which is also where the exact
pins live.
You can force an interpreter with --python, but it has to satisfy every
backend you asked for. A combination that cannot work, such as
--python 3.10 --engines uma, is refused before anything is installed; the
installer never quietly picks a different version.
Check the install¶
.venv-mace/bin/mliport doctor --engine mace --device auto
.venv-dpa/bin/mliport doctor --engine dpa --device auto
.venv-grace/bin/mliport doctor --engine grace --device auto
.venv/bin/mliport doctor --engine uma --device auto
.venv-nep/bin/mliport doctor --engine nep --device cpu # if you installed NEP
Each command exits 0 when the required checks pass and ends with a line such as
Environment checks passed for MACE on CUDA. The report also lists optional
features (TUI, analysis, transport, electrolyte, plotting). To try a real
model, add --model PATH --task TASK --structure FILE. doctor --json gives
the same report in a machine-readable form, handy for cluster provisioning.
Running mliport¶
Call the CLI from the environment that owns the backend:
.venv-mace/bin/mliport sp structure.cif --model model.model --model-type mace
.venv-dpa/bin/mliport sp structure.cif --model model.pt --model-type dpa --head Omat24
.venv-grace/bin/mliport sp structure.cif --model saved_model --model-type grace
.venv/bin/mliport sp structure.cif --model uma.pt --model-type uma
.venv-nep/bin/mliport sp structure.cif --model nep.txt --model-type nep --nep-runtime ase --device cpu
The launchers in ./bin/ run exactly these commands. On Windows each
environment has a Scripts\mliport.exe, and the installer writes
bin\mliport-*.cmd launchers next to the POSIX ones:
DPA and GRACE and the GPU¶
DPA and GRACE cannot move a CUDA context once their framework has loaded. When
CUDA_VISIBLE_DEVICES is not set, the CLI restarts the same command in a fresh
process with the GPU you asked for visible, and prints a short note saying so.
The Python API cannot restart its caller, so if you use DPA or GRACE from
Python, set CUDA_VISIBLE_DEVICES (or "" for CPU) before importing the
framework.
Models¶
mliport does not download checkpoints. Fetch one with the upstream tool and pass
its path with --model; a local file works offline. Where to get the
checkpoints, and the pinned file names and SHA-256 values used by the validation
suite, are on the Models page.
If you download from Hugging Face through a SOCKS proxy, install httpx[socks]
in the environment you download with, and keep NO_PROXY free of bracketed
entries such as [::1], which httpx rejects. HF_ENDPOINT=https://hf-mirror.com
selects the Hugging Face mirror some sites use. The installer itself goes
through uv, which reads the same proxy variables.
GPU architectures¶
PyTorch and TensorFlow ship different CUDA builds for different GPU
generations, and the installer picks the right one for yours: Maxwell, Pascal
and Volta use the cu126 legacy channel, Turing and newer use cu128 or later.
The CUDA 13 channel (cu130, which the UMA runtime uses from torch 2.13)
requires an NVIDIA driver of 580 or newer, and it carries no kernels below
Turing — Volta therefore stays on cu126, which works with older drivers.
mliport setup prints the GPU it detected and the route it would take.
| Engine | Maxwell | Pascal | Volta / V100 | Ada / RTX 4090 | Other Turing+ | Hopper / Blackwell |
|---|---|---|---|---|---|---|
| UMA | experimental | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test |
| MACE | experimental | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test |
| DPA | experimental | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test |
| NEP | experimental | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | experimental |
| GRACE | experimental | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | needs runtime smoke test | experimental |
Read the cells carefully: experimental means the upstream framework does not
test that GPU family, and needs runtime smoke test means a route exists but
mliport has not recorded a real run on that hardware. Neither means "verified".
Only the V100 has hardware evidence. The other families are classified from a
close inspection of the wheels and native extensions: the compiled architecture
lists, the +cu126/+cu128 wheel hashes and the cuobjdump output are in the
architecture report.
mliport doctor prints that classification for the GPU it finds instead of
claiming a verification.
Pre-Turing GPUs depend on the CUDA 12.6 channel, and PyTorch stops publishing it from 2.15. In those environments keep the installer's pins and do not upgrade the framework; a CUDA 13 build is not an alternative there, because it has no kernels below Turing regardless of the driver.
Offline machines¶
Point --source offline at a prepared wheel cache, or install on a connected
machine and copy the environments over. Only two things move: uv's cache
(UV_CACHE_DIR) and the model directory. UV_PYTHON_DOWNLOADS=never stops the
installer from fetching a managed interpreter.
Disk space and removal¶
A four-engine GPU install takes roughly 25–35 GB, most of it PyTorch and
TensorFlow; a CPU install is smaller. To remove a backend, delete its
environment directory (.venv-mace, .venv-dpa, .venv-grace, .venv-nep or .venv).
The repository and your model files are untouched, and the ./bin/mliport-*
launchers go with the bin/ directory. Run the installer again to recreate an
environment.
Installing by hand¶
Every backend environment needs mliport itself plus that engine's stack. The
authoritative pins are in mliport/mliport/install/compatibility.py, and the
installer is the only path that keeps them consistent with your GPU
architecture. If you do it by hand anyway, create one environment per backend,
install ./mliport into each, and run mliport doctor there; do not trust
results until every check passes. Installing mliport once and expecting it to
reach into the other environments will not work.