Installation Guide

Installation Methods

CUDA-QX provides multiple installation methods to suit your needs:

pip install

The simplest way to install CUDA-QX is via pip. (If you’re on Mac, your only option is to use the Docker container as described below.)

# Install QEC library
pip install cudaq-qec

CUDA-QX provides optional pip-installable components:

# Install the Tensor Network Decoder from the QEC library
pip install cudaq-qec[tensor-network-decoder]

Note

Looking for CUDA-Q Solvers? It has been removed from CUDA-QX and is superseded by CUDA-Q Algorithms, which is where development continues:

pip install cudaq-algorithms

See the CUDA-Q Algorithms documentation for installation instructions, tutorials, and examples, cudaq-algorithms on PyPI for the package, and NVIDIA/cudaq-algorithms on GitHub for the source code.

Docker Container

CUDA-QX is available as a Docker container with all dependencies pre-installed:

  1. Pull the container:

docker pull ghcr.io/nvidia/cudaqx

  1. Run the container:

docker run --gpus all -it ghcr.io/nvidia/cudaqx

Note

If your system does not have local GPUs (eg. a MacBook), omit the --gpus all argument.

The container includes:

  • CUDA-Q compiler and runtime

  • CUDA-QX libraries (QEC)

  • All required dependencies

  • Example notebooks and tutorials

Building from Source

The instructions for building CUDA-QX from source are maintained on our GitHub repository: Building CUDA-QX from Source.

Installing PyTorch

PyTorch (torch) is required for several CUDA-QX features:

  • Tensor Network Decoder: Used by the QEC library for tensor network-based decoding (CPU version of PyTorch is sufficient)

  • Training AI Decoders: Optionally used for training custom neural network decoders (see Deploying AI Decoders with TensorRT)

PyTorch is automatically installed when you install the optional components:

# Installs PyTorch as a dependency
pip install cudaq-qec[tensor-network-decoder]

Alternatively, you can install PyTorch directly. For detailed installation instructions, visit the PyTorch installation page.

pip install torch

Note

Users with NVIDIA Blackwell architecture GPUs require PyTorch with CUDA 12.8 or later support. When installing PyTorch, make sure to select the appropriate CUDA version for your system.