> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/cuda/cupotential/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/cuda/cupotential/_mcp/server.

# Installation

> Install the cuPotential OpenMM plugin from PyPI or a GitHub release.

Each [GitHub release](https://github.com/NVIDIA/cuPotential/releases) includes
a pip wheel, a conda package and channel, and a source archive.

We recommend installing and running the plugin in the provided Docker
environment. It includes OpenMM 8.4 with CUDA support, the CUDA libraries, and
Python 3.12. Use `./run_docker <command>` to run a command or `./run_docker bash`
to open a shell. The Docker workflow below starts with a clone or source
archive, which contains `run_docker` and its `Dockerfile`.

## Requirements

* An NVIDIA GPU of SM 75, 80, 86, 89, 90, 100, 103 or 120 (Turing through
  Blackwell, including B200).
* The NVIDIA driver R615 or newer, for CUDA 13.4. NVIDIA data center GPUs, and
  the professional RTX GPUs that CUDA forward compatibility supports, also work
  with an older driver of the R535, R570, R580, R590, R595 or R610 branch, through
  CUDA 13.4's forward compatibility package. The Docker environment has the
  package, and the NVIDIA Container Toolkit uses it on an older driver. Outside
  Docker, install `cuda-compat-13-4` from NVIDIA's CUDA repository (`apt` or
  `dnf`) and put `/usr/local/cuda-13.4/compat` on `LD_LIBRARY_PATH`; take it off
  again once the driver is R615 or newer. GeForce GPUs need R615 or newer. See
  [CUDA Forward Compatibility](https://docs.nvidia.com/deploy/cuda-compatibility/forward-compatibility.html).
* Docker with the NVIDIA Container Toolkit, so that `docker run --gpus=all`
  works, for the recommended Docker environment.
* Linux x86-64.
* Python 3.12, for the wheel and the conda package.
* OpenMM 8.4 with its CUDA platform, which the Docker environment brings.

## From PyPI

Install [`nv-openmm-plugin` from PyPI](https://pypi.org/project/nv-openmm-plugin/)
into an environment meeting the Python, OpenMM, CUDA, and GPU requirements above:

```bash
pip install nv-openmm-plugin
```

Installing the PyPI package does not require a repository checkout.

## From GitHub

The steps below use the GitHub release and the repository's Docker environment.

### 1. Get the source

Clone the repository at the release tag:

```bash
git clone --branch v0.3.5 https://github.com/NVIDIA/cuPotential
cd cuPotential
```

Alternatively, download `cupo-nv-openmm-plugin-src-0.3.5+<build>.tar.gz`
from the [release](https://github.com/NVIDIA/cuPotential/releases/tag/v0.3.5)
and unpack it:

```bash
tar -xzf cupo-nv-openmm-plugin-src-0.3.5+*.tar.gz
cd cupo-nv-openmm-plugin-src-0.3.5+*/
```

Run the commands below from the root of the clone or unpacked archive.

### 2. Install the plugin

Each `./run_docker` invocation starts a new container and removes it when the
command finishes. For pip and conda installations, install and run the plugin
in the same `./run_docker bash` session. The lines after `./run_docker bash`
below run inside that shell.

#### With pip

Install the release's wheel with pip. It requires `openmm[cuda13]>=8.4,<8.5`;
the Docker environment already provides a compatible OpenMM installation.

```bash
./run_docker bash
pip install https://github.com/NVIDIA/cuPotential/releases/download/v0.3.5/nv_openmm_plugin-0.3.5-cp312-cp312-manylinux_2_38_x86_64.whl
./plugins/openmm/samples/solvated_systems/run
```

#### With conda

The first command runs on the host and downloads the release's conda channel.
Inside Docker, micromamba creates an environment with the plugin from that
channel and its dependencies from conda-forge, then runs a sample.

```bash
curl -fL https://github.com/NVIDIA/cuPotential/releases/download/v0.3.5/nv-openmm-plugin-conda-channel-0.3.5.tar.gz | tar -xz
./run_docker bash
micromamba create -y -n cupotential -c ./nv-openmm-plugin-conda-channel-0.3.5 -c conda-forge nv-openmm-plugin
micromamba run -n cupotential ./plugins/openmm/samples/solvated_systems/run
```

#### From source

The source archive includes cuPotential's prebuilt libraries in `build/`.
When building from a clone, `run_build` downloads those libraries from the
matching release and verifies them against `SHA256SUMS`. For a private
repository, set `GITHUB_TOKEN` to a token with read access.

##### Build the plugin

From the root of the tree:

```bash
./run_docker plugins/openmm/run_build
```

`run_docker` runs the build in a container with OpenMM, the CUDA toolkit, and
other build dependencies. The first run also builds the image from the
repository's `Dockerfile`. By default, the plugin is built for every supported
GPU architecture. To shorten the build, select one architecture with
`CUDA_ARCHITECTURES=89 ./run_docker plugins/openmm/run_build` (SM 89 in this example).

##### Run the samples

With the plugin you built, from the root of the tree:

```bash
./run_docker                                              # solvated_systems, the default
./run_docker plugins/openmm/samples/alchemical/run
```

The build leaves the plugin's Python package, `nv_openmm_plugin`, in
`plugins/openmm/python/`, and the samples import it from there.
See [Samples](/cuda/cupotential/samples) for example simulations and
[Tests](/cuda/cupotential/tests) for correctness checks. Benchmark results and
instructions are in the [Overview](/cuda/cupotential#benchmarks).

## Outside Docker

You can also install the wheel or conda package outside Docker. Your environment
must provide OpenMM 8.4 with its CUDA platform, the matching CUDA libraries, and
Python 3.12. The repository's `Dockerfile` lists the commands used to install
these dependencies.

## The GPUs the container gets

`./run_docker` gives the container every GPU in the machine by default. Use
`NV_GPU=0 ./run_docker bash` to select the first host GPU. GPU indices start at 0.
`NV_GPU` also accepts GPU UUIDs and comma-separated lists, such as `NV_GPU=0,1`,
using the same selection as `docker run --gpus device=`.

If the GPU disappears in the middle of a run, with "Failed to initialize NVML:
Unknown Error" from `nvidia-smi` or "No compatible CUDA device is available" from
OpenMM, the host probably ran `systemctl daemon-reload`. On a host whose Docker
uses the systemd cgroup driver, that removes the GPUs from every running container
that got them with `--gpus` only. Set `CUPO_DOCKER_ADD_DEVICE_NODES=1` to have
`run_docker` also pass the GPUs' device nodes, `/dev/nvidia*`, with `--device`,
which keeps them: `CUPO_DOCKER_ADD_DEVICE_NODES=1 ./run_docker bash`. `run_docker`
finds each GPU's node with `nvidia-smi` on the host, and prints a warning when it
cannot. NVIDIA's
[troubleshooting page](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/troubleshooting.html#containers-losing-access-to-gpus-with-error-failed-to-initialize-nvml-unknown-error)
describes the issue.