PyQIR

0.12.4 verified Fri May 01 auth: no python

A Python library for generating, parsing, and evaluating Quantum Intermediate Representation (QIR). Current version is 0.12.4, with irregular release cadence, typically 3-4 minor releases per year.

pip install pyqir

Common errors

error AttributeError: module 'pyqir' has no attribute 'evaluate' ↓

cause Trying to import evaluate directly from pyqir instead of pyqir.evaluator.

fix

Replace 'from pyqir import evaluate' with 'from pyqir.evaluator import evaluate'

error ImportError: cannot import name 'SimpleEvaluator' from 'pyqir' ↓

cause SimpleEvaluator is in a submodule, not directly in pyqir.

fix

Replace 'from pyqir import SimpleEvaluator' with 'from pyqir.evaluator import SimpleEvaluator'

error RuntimeError: Unable to find a prebuilt wheel for pyqir on this platform ↓

cause No prebuilt wheel for your platform (e.g., ARM Linux, Python 3.8).

fix

Upgrade to Python >=3.9 or build from source using maturin.

error AttributeError: 'NoneType' object has no attribute 'context' ↓

cause Builder or BasicBlock was used before being properly initialized.

fix

Ensure you create a Context first and pass it to all objects.

Warnings

breaking PyQIR 0.12.0 switched to QIR 2.0 with opaque pointer support, breaking modules generated with older versions. Upgrade your QIR generation code. ↓

fix Use the latest API. See upgrade guide: https://github.com/qir-alliance/pyqir/blob/main/docs/upgrade.md#pyqir-012

deprecated The `evaluate` function and `SimpleEvaluator` may be deprecated in future versions. Prefer newer evaluation APIs if available. ↓

fix Monitor docs for replacement APIs.

gotcha Qubit IDs are not automatically reset; calling `add_qubit()` increments an internal counter. When reusing a builder, qubit indices can become stale. ↓

fix Keep a local reference to qubits or reset the builder context if needed.

gotcha The library is compiled with Rust/PyO3; ensure your Python version is >=3.9. Pre-built wheels may not be available for all platforms (e.g., ARM Linux). ↓

fix Upgrade Python to 3.9+ or use maturin to build from source.

Imports

Builder
```
from pyqir import Builder
```
BasicBlock
```
from pyqir import BasicBlock
```
Context
```
from pyqir import Context
```
Module
```
from pyqir import Module
```
Qubit
```
from pyqir import Qubit
```

__version__

wrong

import pyqir; pyqir.__version__

correct

from pyqir import __version__

Also valid, but direct import is clearer.

evaluate

wrong

from pyqir import evaluate

correct

from pyqir.evaluator import evaluate

evaluate is a submodule.

SimpleEvaluator

wrong

from pyqir import SimpleEvaluator

correct

from pyqir.evaluator import SimpleEvaluator

SimpleEvaluator is in evaluator submodule.

__qir__
```
from pyqir import __qir__
```
Provides access to QIR constants.

Quickstart

Create a simple QIR module with a Hadamard and measurement, then evaluate it.

from pyqir import Builder, BasicBlock, Context, Module, Qubit
from pyqir.evaluator import evaluate

context = Context()
module = Module(context)
builder = Builder(context)
entry = BasicBlock(context, "entry", module)
builder.insert_at_end(entry)
qubit = builder.add_qubit()
builder.h(qubit)
builder.mz(qubit)
result = evaluate(module, {})
print(result)