Installation instructions

April 17, 2026 · View on GitHub

Quantum++ is a header-only library that uses CMake as its build/install system. Quantum++ is platform-independent, supporting UNIX (including macOS) and UNIX-like operating systems (e.g., Linux), as well as Windows.

Pre-requisites

C++17 compliant compiler, e.g., GCC, Clang, MSVC etc.
CMake
Eigen linear algebra library. If missing, it will be installed automatically by CMake as a build dependency.

Optional

Python 3 for building and running the pyqpp Python 3 wrapper
MATLAB compiler shared libraries and include header files, in case you want to enable interoperability with MATLAB. If enabled, allows applications built with Quantum++ to save/load Quantum++ matrices and vectors to/from MATLAB.

Configuring the system

First configure the system via CMake to use an out-of-source build directory (e.g., ./build) by executing (in a terminal/console/command prompt) under the project's root directory

cmake -B build

Examples

To build the examples, execute

cmake --build build --target examples --parallel 8

This will compile all example executables into ./build/examples. The --parallel 8 flag instructs CMake to build in parallel using 8 threads, modify accordingly.

To build only a specific target, execute, e.g.,

cmake --build build --target bb84

The command above builds only the example examples/bb84.cpp and outputs the executable ./build/examples/bb84[.exe].

Unit tests

Quantum++ provides a set of unit tests implemented using GoogleTest.

Building the unit tests

Quantum++ unit tests are disabled by default. To enable and build the unit tests, configure CMake with unit testing enabled

cmake -B build -DQPP_ENABLE_TESTING=ON

To build the unit tests, execute

cmake --build build/unit_tests --target unit_tests --parallel 8

Tu run the unit tests, execute

ctest --test-dir build

Benchmarks

See benchmarks/README.md for details on how to compile and run the benchmarks.

CMake configuration options

Note: All CMake configuration options below do not propagate to downstream projects that use > Quantum++ via find_package(qpp ...).

Projects linking against Quantum++ must explicitly define these options themselves if required.

Option	Values (default)	Description
`CMAKE_INSTALL_PREFIX`	`/path/to/install`	Specifies a custom installation directory for Quantum++ header files -- useful when you lack administrative privileges or want a non-default install location

`QASMTOOLS_QASM2_SPECS`	`ON/OFF` (`OFF`)	Enables/disables using the OpenQASM 2.0 standard instead of Qiskit specifications -- see `DISCREPANCIES.md`

`QPP_BIGINT`	`default`, etc. (`default`)	Signed big integer type (`qpp::bigint`)
`QPP_FP`	`default`, etc. (`default`)	Floating-point type (`qpp::realT`)
`QPP_IDX`	`default`, etc. (`default`)	Integer index type (`qpp::idx`)

`QPP_ENABLE_PYQPP`	`ON/OFF` (`OFF`)	Enables pyqpp C++ development, disabled by default
`QPP_ENABLE_TESTING`	`ON/OFF` (`OFF`)	Enables unit testing with GoogleTest, disabled by default
`QPP_MATLAB`	`ON/OFF` (`OFF`)	Enables (if available) or disables interoperability with MATLAB (with automatic detection); when enabled, applications can save/load Quantum++ matrices and vectors to/from MATLAB; if CMake fails to detect MATLAB, pass the flag `-DMatlab_ROOT_DIR=/path/to/MATLAB`

`QPP_OPENMP`	`ON/OFF` (`ON`)	Enables (if available)/disables OpenMP multi-processing library
`QPP_QUBIT_OPTIMIZATIONS`	`ON/OFF` (`ON`)	Enables optimized code paths for qubit-only systems (d = 2)
`QPP_NO_THREAD_LOCAL`	`ON/OFF` (`OFF`)	Disables `thread_local` storage duration
`QPP_SANITIZE`	`ON/OFF` (`OFF`)	Enables code sanitizing

Installing Quantum++

UNIX/UNIX-like/Windows

To install Quantum++ (after Configuring the system), execute in a terminal/console (UNIX/UNIX-like systems)

sudo cmake --build build --target install

or in an Administrator Command Prompt (Windows)

cmake --build build --target install

The above commands install Quantum++ in /usr/local/include/qpp on UNIX/UNIX-like platforms, and in C:\Program Files (x86)\qpp on Windows platforms.

To uninstall, execute in a terminal/console (UNIX/UNIX-like systems)

sudo cmake --build build --target uninstall

or in an Administrator Command Prompt (Windows)

cmake --build build --target uninstall

FreeBSD

We are proud to be part of the FreeBSD operating system as an official ports package. If you are using FreeBSD, you can install Quantum++ by running

sudo pkg install quantum++

and uninstall it with

sudo pkg remove quantum++

macOS/Linux

If you are running macOS or Linux, you can install Quantum++ via Homebrew with

brew install quantum++

and uninstall it with

brew uninstall quantum++

Building and running a standalone application that uses Quantum++

Below is a minimal CMakeLists.txt of a standalone application that uses Quantum++. For simplicity, we assume that the whole application is located in a single file src/main.cpp, and the CMakeLists.txt is located in the project's root directory.

cmake_minimum_required(VERSION 3.20)
project(standalone LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

# If Quantum++'s installation path was non-standard, i.e., specified by
#
# cmake -B build -DCMAKE_INSTALL_PREFIX=/path/to/installed/qpp
#
# uncomment the following line and replace the installation path with yours

# set(CMAKE_PREFIX_PATH "/path/to/installed/qpp")

find_package(qpp REQUIRED)

add_executable(standalone src/main.cpp)
target_link_libraries(standalone PRIVATE qpp::qpp)

Configure the application in an out-of-source directory by executing

cmake -B build

followed by building the application with

cmake --build build

The commands above builds the standalone executable inside the build directory.

Building and running a standalone application that uses Quantum++ without a build system

Quantum++ is a header-only library. Hence, you can technically build an application that uses Quantum++ without using a building system, by simply using the compiler and specifying the location to all required dependencies, like below (assumes UNIX/UNIX-like, adapt accordingly for Windows)

g++ -pedantic -std=c++17 -Wall -Wextra -Weffc++ -fopenmp \
    -O3 -DNDEBUG -DEIGEN_NO_DEBUG
    -isystem $HOME/eigen -I $HOME/qpp/include -I $HOME/qpp/qasmtools/include \
     src/main.cpp -o executable_name

If you intend to go via this route, we assume that you are familiar with how compilers work, so we won't add any more explanations to what the line above does.

Additional platform-specific instructions

macOS specific instructions

We highly recommend installing clang via Homebrew, since the native AppleClang does not offer OpenMP support.
In case you get any compiler or linker errors when OpenMP is enabled, you need to install the libomp package, e.g., execute

brew install libomp

MATLAB support under Windows

If building under Windows with MATLAB support, please add the location of libmx.dll and libmat.dll (the .dll and not the .lib files) to your PATH environment variable. For example, on our platform they are located under C:\Program Files\MATLAB\R2021a\bin\win64.

Python 3 wrapper

pyqpp is a Python 3 wrapper for Quantum++. pyqpp requires the same dependencies as Quantum++, and can be installed using pip

pip install git+https://github.com/softwareQinc/qpp

For more details, please see pyqpp/README.md.

Platform-dependent issues

SunOS/OpenIndiana

The Python 3 wrapper pyqpp doesn't compile under SunOS/OpenIndiana due to errors in <cmath> such as

no member named 'llround' in the global namespace; did you mean 'lround'?