Installing QRMI#

Learn how to install QRMI and explore information about further resources.

Quick Start#

We encourage installing QRMI via pip:

pip install qrmi

To use a specific quantum resource, install QRMI with the corresponding optional dependencies:

pip install "qrmi[ibm]"       # Include dependencies for IBM
pip install "qrmi[iqm]"       # Include dependencies for IQM
pip install "qrmi[pasqal]"    # Include dependencies for Pasqal
pip install "qrmi[alice-bob]" # Include dependencies for Alice and Bob
pip install "qrmi[all]"       # Include dependencies for all quantum resources except `alice-bob`

Or combine multiple resources:

pip install "qrmi[ibm,pasqal]"

Note

ibm and iqm extras cannot be installed together, as they depend on incompatible versions of Qiskit.

Note

alice-bob cannot be installed alongside ibm or iqm, as it depends on Qiskit versions earlier than 2.0.

Pip will handle all dependencies automatically and you will always install the latest (and most thoroughly tested) version.

Installing from Source#

Prerequisites#

  • Compilation requires the following tools:

    • Rust compiler 1.98 or above

    • A C compiler

      • For example, GCC (gcc) on Linux and Clang (clang-tools-extra) for Rust unknown targets/cross compilations. QRMI is compatible with a compiler conforming to the C11 standard.

    • make/cmake (make/cmake RPM for RHEL compatible OS)

    • Python 3.11, 3.12 or 3.13 (for Python API)

      • Libraries and header files needed for Python development (python3.1x-devel RPM for RHEL compatible OS)

        • /usr/include/python3.1x

        • /usr/lib64/libpython3.1x.so

    • Standard Lua (PUC-Rio Lua 5.1-5.4)

    • QRMI Standalone C library & header

  • Runtime requires the following tools:

    • gcc (libgcc RPM for RHEL compatible OS)

    • Python 3.11, 3.12 or 3.13 (for Python API)

      • Libraries and header files needed for Python development (python3.1x-devel RPM for RHEL compatible OS)

  • Doxygen (for generating C API document):

    • dnf install doxygen for Linux(RHEL/CentOS/Rocky Linux etc.)

    • apt install doxygen for Linux(Ubuntu etc.)

    • brew install doxygen for MacOS

Building Core QRMI Libraries#

Core QRMI is a set of libraries to control the state of quantum resources. It is written in Rust with C, Python and Lua APIs exposed for ease of integration into any compute infrastructure.

QRMI Source Code#

QRMI’s source code can be cloned from the GitHub repository using the following command:

git clone https://github.com/qiskit-community/qrmi.git

Alternatively, the latest prebuilt binaries for Linux (glibc 2.28 compatible) on x86_64, ppc64le, and aarch64 platforms are available for download from the repository’s Releases tab.

Building from Source#

This section will guide you through building QRMI for C, Python and Lua.

. ~/.cargo/env
cargo clean
cargo build --locked --release

Installing Lua Bindings#

For RHEL / Clone OS installs (Rocky Linux 9, AlmaLinux 8), you need to enable the additional repository (CRB or PowerTools) to install the development packages (-devel).

sudo dnf config-manager --set-enabled crb
sudo dnf install lua lua-devel

Once installed, the Lua binding can be built using either gcc or cmake:

Assuming the qrmi.h and libqrmi.so live in the same directory (<QRMI_ROOT>, e.g. /path/to/qrmi):

gcc -shared -fPIC -O2 $(pkg-config --cflags lua5.4) \
   -I/path/to/qrmi \
   -o qrmi.so lua_qrmi.c \
   -L/path/to/qrmi -lqrmi \
   $(pkg-config --libs lua5.4) \
   -Wl,-rpath,/path/to/qrmi

  • -I/path/to/qrmi — lets the compiler find qrmi.h

  • -L/path/to/qrmi -lqrmi — links against libqrmi.so

  • -Wl,-rpath,/path/to/qrmi — bakes that directory into qrmi.so’s RUNPATH, so LD_LIBRARY_PATH doesn’t need to be set at runtime (verify with readelf -d qrmi.so)

Building Optional Libraries#

There are optional packages available to install within the QRMI repository.

Building task_runner#

task_runner is a command line tool to execute quantum payloads against quantum hardware. Under the hood, it uses the QRMI library.

task_runner for Python is already included in the QRMI Python package. Users can use the task_runner` command after installing qrmi. For detailed instructions on how to use it, please refer to the task_runner README.

Build with Munge support for Pasqal Local#

By default, QRMI is built without Munge support. If you need to use the Pasqal Local client which relies on Munge for authentication, you must enable the munge feature during the build process.

  1. Build the Rust library:

. ~/.cargo/env
cargo build --release --features munge

  1. Build the Python wheels:

source ~/py312_qrmi_venv/bin/activate
CARGO_TARGET_DIR=./target/release/maturin maturin build --release --features munge,pyo3/abi3,qrmi/pyo3

Further Resources#

Examples#

A range of example code is available within this knowledge base. Each example provides detailed instructions and a link to the directory’s GitHub location. You can find links to language-specific examples below:

QRMI is workload manager agnostic and supports a range of workload managers via plugins. One example of QRMI usage in a compute infrastructure project is the Slurm plugin for quantum resources. QRMI is used in these Slurm plugins to control quantum resources during the lifecycle of a Slurm job. You can find full details on implementing the Quantum SPANK plugins for Slurm here.

The Slurm plugin for quantum resources is only one example of QRMI’s workload manager integrations. More information about QRMI’s integrations is available in our Quantum-HPC Integration paper.

Logging#

QRMI supports log crate for logging. You can find the detailed QRMI runtime logs by specifying the RUST_LOG environment variable with log level. Supported levels are error, warn, info, debug and trace. The default level is warn.

If you specify trace, you can find underlying HTTP transaction logs.

RUST_LOG=trace <YOUR QRMI EXECUTABLE>

[2025-08-16T03:47:38Z DEBUG reqwest::connect] starting new connection: https://iam.cloud.ibm.com/
[2025-08-16T03:47:38Z DEBUG direct_access_api::middleware::auth] current token ...

API Documentation#

Links to the Python, Rust, C and Lua API documentation are available here:

The Python, Rust and C API documentation can be built locally using our API references guide.

Packaging#

How to package libqrmi for RHEL 8 based Linux#

git clone https://github.com/qiskit-community/qrmi.git
cd qrmi
./run_in_container.sh make libqrmi-

The packages below will be created under ./rpmbuild/RPMS/:

  • libqrmi — runtime shared library (libqrmi.so.0), needed at runtime

  • libqrmi-devel — header (qrmi.h) + unversioned symlink (libqrmi.so), needed only when compiling applications against the library

Note

The command above will automatically create the required source and vendor tarballs. If you prefer, you could rather download them from the latest QRMI release published , renaming them accordingly to ./qrmi-<version>.tar.gz and ./qrmi-<version>-vendor.tar.gz.

How to install the libqrmi RPMs in a RHEL 8 based Linux system#

dnf install ./libqrmi-*.rpm

Contributing#

Whether you are part of the core team or an external contributor, welcome and thank you for contributing to QRMI implementations!

You can learn more about contributing to the development of QRMI using our contribution guidance.

Linting/Formatting#

For guidance on how to solve linting/formatting issues, and executing the necessary checks before submitting a PR, follow our style and linting documentation.

Help and Support#

If you require support, our help and support documentation provides up-to-date links to further guidance and our communication channels. Please don’t hesitate to get in touch!

License#

Apache-2.0