hugr-qir

A tool for converting Hierarchical Unified Graph Representation (HUGR, pronounced hugger) formatted quantum programs into QIR format.

Documentation

Project documentation lives in docs/ and can be viewed online here.

Getting started: docs/getting-started.md
Examples: docs/examples/index.md
Guppylang support: docs/guppy-for-h-series/index.md
Python API: docs/python-api.md
CLI: docs/cli.md
WASM support: docs/wasm.md
Development: docs/development.md

To build the documentation locally:

uv run --group docs sphinx-build -M html docs docs/_build

Then open docs/_build/html/index.html in a browser.

Installation

You can install from pypi via pip install hugr-qir.

Usage

Python

Use hugr_to_qir to convert a HUGR package or serialized HUGR bytes into QIR.

from hugr_qir.hugr_to_qir import hugr_to_qir
from hugr_qir.output import OutputFormat

qir = hugr_to_qir(
    hugr_package,
    validate_qir=False,
    output_format=OutputFormat.LLVM_IR,
)

By default, basic validity checks are run on the generated QIR. These can be disabled by passing validate_qir=False.

You can find an example notebook at examples/submit-guppy-h2-via-qir.ipynb showing the conversion and the submission to Quantinuum System Model H2.

CLI

You can use the available CLI after installing the python package.

This will generate qir for a given hugr file:

hugr-qir test-file.hugr

Run hugr-qir --help to see the available options.

If you want to generate a HUGR file from Guppy, you can do this in two steps:

Add this to the end of your guppy file:

if __name__ == "__main__":
    sys.stdout.buffer.write(main.compile().to_bytes())
    # Or to compile a non-main guppy function:
    sys.stdout.buffer.write(guppy_func.compile_function().to_bytes())

Generate the hugr file with:

python guppy_examples/general/quantum-classical-1.py > test-guppy.hugr

See docs/guppy-for-h-series/support-matrix.md for the current Guppylang support matrix and caveats.

Development

Setting up the development environment

The easiest way to set up the development environment is to use the provided devenv.nix file. This will set up a development shell with all the required dependencies.

To use this, you will need to install devenv. Once you have it running, open a shell with:

devenv shell

All the required dependencies should be available. You can automate loading the shell by setting up direnv.

Run tests

You can run the rust test with:

cargo test

You can run the Python test with:

uv run pytest -n auto

You can type-check the Python sources with:

uv run ty check

You can run the Python formatter and linter with:

uv run ruff format --check python guppy_examples
uv run ruff check python guppy_examples

You can run the configured Git hooks with:

uvx prek run --all-files

If you want to update the snapshots you can do that via:

uv run pytest --snapshot-update

License

This project is licensed under Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0).

Metadata

Release files for hugr-qir 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hugr-qir 0.3.0
File	Size	Uploaded
hugr_qir-0.3.0.tar.gz	1.6 MB	Sep 17, 2026	Details

Built distributions (wheels)

Table of built distributions (wheels) for hugr-qir 0.3.0
File	Interpreter	ABI	Platform	Reset
hugr_qir-0.3.0-cp310-abi3-win_amd64.whl 25.1 MB Sep 17, 2026	CPython 3.10	abi3	Windows x86-64	Details
hugr_qir-0.3.0-cp310-abi3-manylinux_2_34_x86_64.whl 35.3 MB Sep 17, 2026	CPython 3.10	abi3	Linux glibc 2.34+ x86-64	Details
hugr_qir-0.3.0-cp310-abi3-macosx_13_0_x86_64.whl 26.7 MB Sep 17, 2026	CPython 3.10	abi3	macOS 13.0+ x86-64	Details
hugr_qir-0.3.0-cp310-abi3-macosx_13_0_arm64.whl 25.2 MB Sep 17, 2026	CPython 3.10	abi3	macOS 13.0+ ARM64	Details

Total release size: 113.9 MB

Release files / hugr_qir-0.3.0.tar.gz

Download URL	hugr_qir-0.3.0.tar.gz
Size	1.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`4444ba66e5000513e3b6c10fe30516f7452eeafa352a331bddf44370284924ad`
BLAKE2b-256 checksum How to use checksums	`fe227a06bac6a3604ce43e8e4285d8e707e1abfb539eb219c5c7f750728791d1`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`

Release files / hugr_qir-0.3.0-cp310-abi3-win_amd64.whl

Download URL	hugr_qir-0.3.0-cp310-abi3-win_amd64.whl
Size	25.1 MB
Tags	CPython 3.10 Windows x86-64 abi3
SHA-256 checksum How to use checksums	`26ba4b9d72bf05618f9c9a2a08c421be6a8928d9c5e560888b4b0a964c0705d5`
BLAKE2b-256 checksum How to use checksums	`e23fbe4480ec0edd0395a4f57bb3290ea4eaf0e7a077334d9f2c0906f6ce3822`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`

Release files / hugr_qir-0.3.0-cp310-abi3-manylinux_2_34_x86_64.whl

Download URL	hugr_qir-0.3.0-cp310-abi3-manylinux_2_34_x86_64.whl
Size	35.3 MB
Tags	CPython 3.10 Linux glibc 2.34+ x86-64 abi3
SHA-256 checksum How to use checksums	`4e8c699906fe062e450906848ed1603410e14d93ec4edbf0d3363b21767c5e25`
BLAKE2b-256 checksum How to use checksums	`15aa6d4ff9d3f85d568e0292eddfba5eeae4ddfe3d090788b4ec449294c39601`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`

Release files / hugr_qir-0.3.0-cp310-abi3-macosx_13_0_x86_64.whl

Download URL	hugr_qir-0.3.0-cp310-abi3-macosx_13_0_x86_64.whl
Size	26.7 MB
Tags	CPython 3.10 abi3 macOS 13.0+ x86-64
SHA-256 checksum How to use checksums	`2b07aa7d54feaa47bda15aaca120620e4a800d32eaa11a313d219e38ac2e5d58`
BLAKE2b-256 checksum How to use checksums	`2ddc795b1544d0114a0e78a00abbe18cc4c2e76e13001fdad85369af81d8634e`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`

Release files / hugr_qir-0.3.0-cp310-abi3-macosx_13_0_arm64.whl

Download URL	hugr_qir-0.3.0-cp310-abi3-macosx_13_0_arm64.whl
Size	25.2 MB
Tags	CPython 3.10 abi3 macOS 13.0+ ARM64
SHA-256 checksum How to use checksums	`21c66c64c9a2e1b880321b51f0e20e4da10577f565f3c3e7a571e59ea17afdec`
BLAKE2b-256 checksum How to use checksums	`99398102cfeeb4ae3abd33c161f1e37cdb41fc74ff6440454edfc29277274a32`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`maturin/1.15.0`