Installation Guide

Installation Methods

CUDA-Q QEC provides multiple installation methods to suit your needs:

pip install

The simplest way to install CUDA-Q QEC 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-Q QEC 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 this repository 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-Q QEC 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-Q QEC library

  • All required dependencies

  • Example notebooks and tutorials

Building from Source

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

Installing PyTorch

PyTorch (torch) is required for several CUDA-Q QEC 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.