Skip to content

Installation

pip install gpuma

This installs gpuma together with its core dependencies. At the moment, installation and tests have only been validated under Python 3.12; using other Python versions is currently considered experimental.

GPU support

By default, pip install may pull a CPU-only build of PyTorch (especially on Windows). To enable GPU acceleration, install PyTorch with CUDA before installing GPUMA.

Visit pytorch.org/get-started to get the install command matching your platform and CUDA version, e.g.:

pip install torch --index-url https://download.pytorch.org/whl/cu124

Then install GPUMA — pip will see that a CUDA-enabled PyTorch is already present and will not replace it:

pip install gpuma

This pulls in all model backends (Fairchem UMA, ORB-v3, and SevenNet) as core dependencies — there is no separate optional extra to install.

GPU conformer embedding

SMILES → 3D conversion can run on the GPU via nvMolKit, which is a core dependency and installs automatically from PyPI (it pins rdkit==2026.3.1 to match the RDKit build it is linked against, so no extra package index is needed). The backend is selected by technical.device: a CUDA device uses nvMolKit, otherwise the CPU (morfeus) backend is used. The GPU path needs an NVIDIA GPU (compute capability 7.0+); on CPU-only machines the package still installs and the CPU backend is used.

Environment setup examples

  • Using a uv virtual environment 

    # create and activate a fresh environment (Python 3.12)
uv venv .venv --python 3.12

# activate the environment

# install PyTorch with CUDA support (pick your CUDA version at https://pytorch.org)
uv pip install torch --index-url https://download.pytorch.org/whl/cu124

# install gpuma from PyPI inside the environment
uv pip install gpuma

  • Using a conda environment 

    # create and activate a fresh environment with Python 3.12
conda create -n gpuma-py312 python=3.12
conda activate gpuma-py312

# install PyTorch with CUDA support (pick your CUDA version at https://pytorch.org)
pip install torch --index-url https://download.pytorch.org/whl/cu124

# install gpuma from PyPI inside the environment
pip install gpuma

⚠️ Required for UMA models:
To access the UMA models on Hugging Face, you must provide a token either via the HUGGINGFACE_TOKEN environment variable or via the config (direct token string or path to a file containing the token).

Option 2: Install from source

# clone the repository
git clone https://github.com/niklashoelter/gpuma.git
cd gpuma

# install PyTorch with CUDA support (pick your CUDA version at https://pytorch.org)
pip install torch --index-url https://download.pytorch.org/whl/cu124

# install using (uv) pip
uv pip install .
# or, without uv:
pip install .