Ctrl+K

Installation Guide#

There are a number of ways to download and setup a Python environment for nvalchemi-toolkit, depending on whether you are a user, a developer, what optional dependencies you would like to include, what version of CUDA Toolkit is available, and what environment manager you use.

From PyPI#

The most straightforward way to install ALCHEMI Toolkit is via PyPI. Choose one accelerator stack, then add any compatible optional extras.

Package manager
Accelerator
Optional extras
Run this command
pip install nvalchemi-toolkit

Note

The CUDA extras are mutually exclusive. The uma extra is also mutually exclusive with cu12, cu13, and mace; keep UMA in a separate environment.

Note

We recommend using uv for virtual environment, package management, and dependency resolution. uv can be obtained through their installation page found here. Alternative environment managers like pyenv can also be used for pip exclusive commands.

From Github Source#

This approach is useful for obtain nightly builds by installing directly from the source repository:

$ pip install git+https://www.github.com/NVIDIA/nvalchemi-toolkit.git

Installation via uv#

Maintainers generally use uv, and is the most reliable (and fastest) way to spin up a virtual environment to use ALCHEMI Toolkit. Assuming uv is in your path, here are a few ways to get started:

Stable, without cloning

This method is recommended for production use-cases, and when using ALCHEMI Toolkit as a dependency for your project. The Python version can be substituted for any other version supported by ALCHEMI Toolkit.

$ uv venv --seed --python 3.12
$ uv pip install \
    --torch-backend cu130 \
    --index-strategy unsafe-best-match \
    'nvalchemi-toolkit[cu13]'

For MACE and cuEquivariance support, select the matching variant:

# CUDA 13 MACE stack
$ uv pip install \
    --torch-backend cu130 \
    --index-strategy unsafe-best-match \
    'nvalchemi-toolkit[cu13,mace]'

# CUDA 12 MACE stack
$ uv pip install \
    --torch-backend cu126 \
    --index-strategy unsafe-best-match \
    'nvalchemi-toolkit[cu12,mace]'

Tip

The --torch-backend option routes uv to install the correct set of extra libraries more explicitly. For machines without accelerators, such as on MacOS development, this option can be omitted. Conversely, on machines with a GPU and for whatever reason want to force the installation to be CPU only, you can specify cpu as a backend.

Nightly, with cloning

This method is recommended for local development and testing.

$ git clone git@github.com:NVIDIA/nvalchemi-toolkit.git
$ cd nvalchemi-toolkit
$ uv sync --extra cu13
# include documentation tools with --group docs

uv sync creates or updates the repository .venv, installs the local nvalchemi-toolkit package in editable mode, installs the default dependency groups configured for the project, and uses uv.lock for reproducible versions. Select exactly one CUDA extra when syncing:

# Default development stack: CUDA 13
$ uv sync --extra cu13

# CUDA 12 stack for systems that have not moved to CUDA 13 yet
$ uv sync --extra cu12

# MACE support follows the same split
$ uv sync --extra cu13 --extra mace
$ uv sync --extra cu12 --extra mace

The CUDA extras are intentionally mutually exclusive. Do not use uv sync --all-extras, because it requests both cu12 and cu13 in the same environment.

Use the same CUDA extra when running commands through uv run. By default, uv run checks and syncs the project environment before executing the command; bare uv run ... does not remember that the environment was previously synced with cu12.

# Default CUDA 13 stack
$ uv run --extra cu13 pytest test/

# CUDA 12 stack
$ uv run --extra cu12 pytest test/

# CUDA 12 stack with MACE support
$ uv run --extra cu12 --extra mace pytest test/

The Makefile threads the selected extra through both uv sync and uv run:

# Default CUDA 13 stack
$ make test

# CUDA 12 stack
$ make test CUDA_EXTRA=cu12

# CUDA 12 stack with MACE support
$ make test CUDA_EXTRA=cu12 OPTIONAL_EXTRAS=mace

After a known-good sync, uv run --no-sync ... can run without modifying the environment, but it also skips uv’s normal environment check.

Additional dependency groups can be layered onto the selected CUDA stack:

# CUDA 13 plus documentation build dependencies
$ uv sync --extra cu13 --group docs

# Verify the environment would sync without changing it
$ uv sync --extra cu13 --dry-run

# Fail if uv.lock would need to change
$ uv sync --extra cu13 --locked
Nightly, without cloning

Warning

Installing nightly versions without cloning the codebase is not recommended for production settings!

$ uv venv --seed --python 3.13
$ uv pip install \
    --torch-backend cu130 \
    --index-strategy unsafe-best-match \
    'nvalchemi-toolkit[cu13] @ git+https://www.github.com/NVIDIA/nvalchemi-toolkit.git'
As a package dependency

To add nvalchemi as a dependency to your project via uv:

# add the last stable version
$ uv add nvalchemi
# nightly version; best practice is to pin to a version release
$ uv add "nvalchemi @ git+https://www.github.com/NVIDIA/nvalchemi-toolkit.git"

Installation with Conda & Mamba#

The installation procedure should be similar to other environment management tools when using either conda or mamba managers; assuming installation from a fresh environment:

# create a new environment named nvalchemi if needed
mamba create -n nvalchemi python=3.12 pip
mamba activate nvalchemi
pip install \
    --extra-index-url https://download.pytorch.org/whl/cu130 \
    'nvalchemi-toolkit[cu13]'

Next Steps#

You should now have a local installation of nvalchemi ready for whatever your use case might be! To verify, you can always run:

$ python -c "import nvalchemi; print(nvalchemi.__version__)"

If that doesn’t resolve, make sure you’ve activated your virtual environment. Once you’ve verified your installation, you can:

  1. Explore examples & benchmarks: Check the examples/ directory for tutorials

  2. Read Documentation: Browse the user and API documentation to determine how to integrate ALCHEMI Toolkit into your application.

On this page
Show Source