Installation#

PhysicsNeMo can be installed in two supported ways: via pip (using native pip or uv) or by using the NVIDIA container image. Choose the method that fits your environment and workflow.

  • Container: Best when you want a pre-built environment with all dependencies. Use the PhysicsNeMo NGC container for training, running examples, or trying the framework.

  • pip / uv: Best when you want to install PhysicsNeMo into an existing Python environment (e.g., conda or venv) or develop from source. Use uv for fast, reproducible installs.

The following scenarios may help you decide:

  • I want to train a model or run PhysicsNeMo examples.

    Use either the container image or a pip/uv install. The container is ready to use; with pip/uv, install PyTorch first, then PhysicsNeMo. See the Training Recipe for a simple training example.

  • I’m a domain expert and want to use or modify an existing model.

    Use either the container or pip/uv. We recommend downloading the examples from GitHub as a starting point.

  • I want to contribute to PhysicsNeMo.

    See Customizing PhysicsNeMo for install-from-source steps and contribution resources.

PhysicsNeMo with Docker Image#

The NVIDIA PhysicsNeMo NGC Container provides PhysicsNeMo and its dependencies pre-installed. The image is based on the NVIDIA PyTorch NGC Container and is optimized for GPU workloads.

Install Docker and NVIDIA Container Toolkit#

Ensure Docker Engine is installed. You also need the NVIDIA Container Toolkit. On many Debian-based systems:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

Verify the setup using the sample workload.

To run Docker without sudo, add your user to the Docker group; see Manage Docker as a non-root user (steps 1–4).

Pull and run the container#

Pull the image from NGC (see PhysicsNeMo NGC Container tags for available tags):

docker pull nvcr.io/nvidia/physicsnemo/physicsnemo:<tag>

Start a shell in the container:

docker run --shm-size=1g --ulimit memlock=-1 --ulimit stack=67108864 \
           --runtime nvidia -it --rm nvcr.io/nvidia/physicsnemo/physicsnemo:<tag> bash

To mount the current directory into the container:

docker run --shm-size=1g --ulimit memlock=-1 --ulimit stack=67108864 \
           --runtime nvidia -v ${PWD}:/workspace \
           -it --rm nvcr.io/nvidia/physicsnemo/physicsnemo:<tag> bash

For multi-GPU runs, use --gpus all (e.g. docker run --gpus all ...).

To verify the installation, see Running examples or run:

python
>>> import torch
>>> from physicsnemo.models.mlp.fully_connected import FullyConnected
>>> model = FullyConnected(in_features=32, out_features=64)
>>> input = torch.randn(128, 32)
>>> output = model(input)
>>> output.shape
torch.Size([128, 64])

PhysicsNeMo with Singularity#

After installing Singularity, build and run the PhysicsNeMo image:

singularity build PhysicsNeMo.sif docker://nvcr.io/nvidia/physicsnemo/physicsnemo:<tag>
singularity run --writable --nv PhysicsNeMo.sif

PhysicsNeMo with pip#

Install PhysicsNeMo into a Python environment (e.g. conda or venv). Install PyTorch for your platform first using the PyTorch install guide, then install PhysicsNeMo.

Basic install (PyPI)#

pip install nvidia-physicsnemo
python -c "import physicsnemo; print('PhysicsNeMo version:', physicsnemo.__version__)"

CUDA backend and optional extras#

To get a CUDA-matched PyTorch build and optional RAPIDS packages, use the cu12 or cu13 extra. Combine with feature extras as needed:

# CUDA 13 with nn-extras
pip install "nvidia-physicsnemo[cu13,nn-extras]"

# CUDA 12 with nn-extras
pip install "nvidia-physicsnemo[cu12,nn-extras]"

Other extras (e.g. utils-extras, mesh-extras, model-extras, datapipes-extras, gnns) can be added in the same way. See the PhysicsNeMo pyproject.toml for the full list.

To verify, see Running examples or run the Hello World snippet shown in the Docker section above.

PhysicsNeMo with uv#

For development or to run examples from the repository, you can use uv to clone and install dependencies:

git clone https://github.com/NVIDIA/physicsnemo.git
cd physicsnemo
uv sync --extra cu13
uv run python -c "import physicsnemo; print('PhysicsNeMo version:', physicsnemo.__version__)"

With optional extras (e.g. nn-extras):

uv sync --extra cu13 --extra nn-extras

For CUDA 12, use cu12 instead of cu13.

Optional dependencies#

  • Examples: Many examples need extra packages. Check each example’s README.md or requirements.txt.

Other PhysicsNeMo library installation guidelines#

The following libraries extend PhysicsNeMo and are installed separately from the core package.

PhysicsNeMo Sym#

PhysicsNeMo Sym adds geometry, PDEs, and physics-informed training utilities. Installation instructions for Sym, and its examples and documentation are in the PhysicsNeMo Sym repository. The Sym repo uses Git LFS; ensure Git LFS is installed before cloning.

PhysicsNeMo Curator#

PhysicsNeMo Curator is a sub-module of PhysicsNeMo framework, a pythonic library designed to streamline and accelerate the crucial process of data curation at scale for engineering and scientific datasets for training and inference.

For installation instructions, refer PhysicsNeMo Curator GitHub .

PhysicsNeMo CFD#

NVIDIA PhysicsNeMo-CFD is a sub-module of PhysicsNeMo framework that provides the tools needed to integrate pretrained AI models into engineering and CFD workflows.

For installation instructions, refer PhysicsNeMo CFD GitHub .

Earth2Studio#

Earth2Studio is a Python-based package designed to get users up and running with AI Earth system models fast.

For installation instructions, refer Earth2Studio Install Guide .

Running examples#

For tutorials and the user guide, see the User Guide.

Example collections:

Each PhysicsNeMo examples come with a README.md for problem description and run instructions. Many examples provide a requirements.txt for extra dependencies.

PhysicsNeMo on public cloud instances#

PhysicsNeMo can run on GPU instances on AWS, GCP, and similar clouds:

  1. Launch a GPU instance (see system requirements for recommended hardware).

  2. Use an NVIDIA GPU-optimized image (e.g. NVIDIA GPU-Optimized VMI on AWS). For setup, see NGC Certified Public Clouds.

  3. After the instance is up, follow the NVIDIA PhysicsNeMo Getting Started to load the PhysicsNeMo container and run examples.