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. You can install individual components:

# Install QEC library
pip install cudaq-qec

# Install Solvers library
pip install cudaq-solvers

# Install both libraries
pip install cudaq-qec cudaq-solvers

Note

CUDA-Q Solvers will require the presence of libgfortran, which is not distributed with the Python wheel, for provided classical optimizers. If libgfortran is not installed, you will need to install it via your distribution’s package manager. On Debian based systems, you can install this with apt-get install gfortran.

Docker Container

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

Pull the container:

docker pull ghcr.io/nvidia/cudaqx

Run the container:

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

The container includes:

CUDA-Q compiler and runtime
CUDA-QX libraries (QEC and Solvers)
All required dependencies
Example notebooks and tutorials

Building from Source

Prerequisites

Before building CUDA-QX from source, ensure your system meets the following requirements:

CUDA-Q: The NVIDIA quantum-classical programming model
CMake: Version 3.28 or higher (pip install cmake>=3.28)
GCC: Version 11 or higher
Python: Version 3.10, 3.11, or 3.12
NVIDIA GPU: CUDA-capable GPU with compute capability 12.0 or higher
Git: For cloning the repository

Build Instructions

Clone the repository:

git clone https://github.com/nvidia/cudaqx
cd cudaqx

Create and enter build directory:

mkdir build && cd build

Configure with CMake:

cmake .. -G Ninja \
    -DCUDAQX_ENABLE_LIBS="all" \
    -DCUDAQX_INCLUDE_TESTS=ON \
    -DCUDAQX_BINDINGS_PYTHON=ON \
    -DCUDAQ_DIR=$HOME/.cudaq/lib/cmake/cudaq \
    -DCMAKE_CXX_FLAGS="-Wno-attributes" \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$HOME/.cudaqx

Build and install:

ninja install

CMake Build Options

CUDAQX_ENABLE_LIBS: Specify which libraries to build (all, qec, solvers)
CUDAQX_INCLUDE_TESTS: Enable building of tests
CUDAQX_BINDINGS_PYTHON: Enable Python bindings
CUDAQ_DIR: Path to CUDA-Q installation
CMAKE_INSTALL_PREFIX: Installation directory

Verifying Installation

To verify your installation, run the following Python code:

import cudaq_qec as qec
import cudaq_solvers as solvers

Troubleshooting (Common Issues)

CMake configuration fails:
- Ensure CUDA-Q is properly installed
- Verify CMake version (cmake --version)
- Check GCC version (gcc --version)
CUDA device not found:
- Verify NVIDIA driver installation
- Check CUDA toolkit installation
- Ensure GPU compute capability is supported
Python bindings not found:
- Confirm CUDAQX_BINDINGS_PYTHON=ON during build
- Check Python environment activation
- Verify installation path is in PYTHONPATH

For additional support, please visit our GitHub Issues page.