> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qbraid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

<div style={{ display: "flex", justifyContent: "center", alignItems: "center" }}>
  <img src="https://mintcdn.com/qbraidco/rzZT9djB25T3PqZG/qir/_static/qir_banner.png?fit=max&auto=format&n=rzZT9djB25T3PqZG&q=85&s=c8475300183e29a9e976463932a66f03" alt="qBraid-QIR" style={{ width: "200", height: "auto", margin: "0" }} width="3840" height="640" data-path="qir/_static/qir_banner.png" />
</div>

<div style={{ textAlign: "center", marginTop: "-8px" }}>
  *qBraid-SDK extension providing support for QIR conversions.*
</div>

## Motivation

<div style={{ display: "flex", alignItems: "center" }}>
  <p style={{ marginRight: "20px" }}>
    This project aims to make <a href="https://www.qir-alliance.org/">QIR</a>{" "}
    representations accessible via the qBraid-SDK{" "}
    <a href="#architecture-diagram">transpiler</a>, and by doing so, open the
    door to language-specific conversions from any and all high-level quantum
    languages [supported](/v2/sdk/user-guide/overview/#supported-frontends) by{" "}
    <code>qbraid</code>.

    See QIR Alliance: <a href="https://www.qir-alliance.org/qir-book/concepts/why-do-we-need.html"> Why do we need it? </a>
  </p>

  <img src="https://mintcdn.com/qbraidco/rzZT9djB25T3PqZG/qir/_static/qir_logo.png?fit=max&auto=format&n=rzZT9djB25T3PqZG&q=85&s=008b87245477d41816fbbf60c7b02e7c" alt="QIR Alliance" style={{ width: "300px", height: "auto", alignSelf: "flex-start" }} width="225" height="165" data-path="qir/_static/qir_logo.png" />
</div>

## Installation

qBraid-QIR requires Python 3.10 or greater, and can be installed with pip as follows:

```shell theme={null}
pip install qbraid-qir
```

### Optional dependencies

qBraid-QIR offers integrations that require extra (optional) dependencies, which can be installed as follows:

For Cirq to QIR conversions, install the `cirq` extra:

```shell theme={null}
pip install 'qbraid-qir[cirq]'
```

For OpenQASM 3 to QIR conversions, install the `qasm3` extra:

```shell theme={null}
pip install 'qbraid-qir[qasm3]'
```

For Squin to QIR conversions, install the `squin` extra:

```shell theme={null}
pip install 'qbraid-qir[squin]'
```

### Install from source

You can also install from source by cloning this repository and running a pip install command
in the root directory of the repository:

```shell theme={null}
git clone https://github.com/qBraid/qbraid-qir.git
cd qbraid-qir
pip install .
```

To include optional dependencies when installing from source, use the same "extras\_require" format, e.g.

```shell theme={null}
pip install '.[cirq,qasm3]'
```

## Check version

You can view the version of qbraid-qir you have installed within a Python shell as follows:

```python theme={null}
In [1]: import qbraid_qir

In [2]: qbraid_qir.__version__
```

## Usage examples

### Cirq conversions

```python theme={null}
import cirq
from qbraid_qir.cirq import cirq_to_qir

q0, q1 = cirq.LineQubit.range(2)

circuit = cirq.Circuit(
  cirq.H(q0),
  cirq.CNOT(q0, q1),
  cirq.measure(q0, q1)
)

module = cirq_to_qir(circuit, name="my-circuit")

ir = str(module)
```

### OpenQASM 3 conversions

```python theme={null}
from qbraid_qir.qasm3 import qasm3_to_qir

program = """
OPENQASM 3;
include "stdgates.inc";

qubit[2] q;
bit[2] c;

h q[0];
cx q[0], q[1];

measure q[0] -> c[0];
measure q[1] -> c[1];
"""

module = qasm3_to_qir(program, name="my-program")

ir = str(module)
```

[Currently Supported Operations](https://github.com/qBraid/qbraid-qir/tree/main/qbraid_qir/qasm3/README.md)

### QIR to Squin conversions

```python theme={null}
from qbraid_qir.squin import load
from pyqir import BasicQisBuilder, SimpleModule

mod = SimpleModule("bell", num_qubits=2, num_results=2)
qis = BasicQisBuilder(mod.builder)

qis.h(mod.qubits[0])
qis.cnot(mod.qubits[0], mod.qubits[1])

squin_kernel = load(mod._module)

squin_kernel.print()
```

### Add QIR node to qBraid conversion graph

```python theme={null}
from qbraid_qir.cirq import cirq_to_qir
from qbraid.transpiler import Conversion, ConversionGraph

graph = ConversionGraph()

conversion = Conversion("cirq", "qir", cirq_to_qir)

graph.add_conversion(conversion)

graph.plot()
```

## Architecture diagram

qBraid-SDK transpiler hub-and-spokes architecture with
qbraid-qir integration (left) mapped to language specific conversion step in QIR abstraction
[layers](https://www.qir-alliance.org/qir-book/concepts/why-do-we-need.html) (right).

<div style={{ display: "flex", justifyContent: "center", alignItems: "center" }}>
  <img src="https://mintcdn.com/qbraidco/rzZT9djB25T3PqZG/qir/_static/qir_architecture.png?fit=max&auto=format&n=rzZT9djB25T3PqZG&q=85&s=411f9a19ec54106989a2c5d1ed47b97f" width="150%" data-path="qir/_static/qir_architecture.png" />
</div>

## Contributing

* Interested in contributing code, or making a PR? See
  [CONTRIBUTING.md](https://github.com/qBraid/qbraid-qir/blob/main/CONTRIBUTING.md)
* For feature requests and bug reports:
  [Submit an issue](https://github.com/qBraid/qbraid-qir/issues)
* For discussions, and specific questions about qBraid-QIR [join our discord community](https://discord.gg/TPBU2sa8Et)
* For questions that are more suited for a forum, post to
  [Quantum Computing Stack Exchange](https://quantumcomputing.stackexchange.com/)
  with the [`qbraid`](https://quantumcomputing.stackexchange.com/questions/tagged/qbraid) tag.

## Citation

If you use qBraid-QIR in your research, we kindly request that you cite it appropriately.
The BibTeX entry below is aligned with the latest stable release. For the most up-to-date
citation details, please refer to [CITATION.cff](https://github.com/qBraid/qbraid-qir/blob/main/CITATION.cff).

```tex theme={null}
@software{Gupta_qBraid-QIR_Python_package_2026,
author = {Gupta, Harshit and and Hill, Ryan James},
license = {Apache-2.0},
month = feb,
title = {{qBraid-QIR: Python package for QIR conversions, integrations, and utilities.}},
url = {https://github.com/qBraid/qbraid-qir},
version = {0.5.1},
year = {2025}
}
```

## Acknowledgements

This project was conceived in cooperation with the Quantum Open Source Foundation ([QOSF](https://qosf.org/)).

<img src="https://mintcdn.com/qbraidco/rzZT9djB25T3PqZG/qir/_static/qosf_logo.png?fit=max&auto=format&n=rzZT9djB25T3PqZG&q=85&s=da98c8d9259f0a02167f7d3239d76943" alt="Quantum Open Source Foundation" style={{ width: "100px", height: "auto", margin: "0" }} width="200" height="200" data-path="qir/_static/qosf_logo.png" />

## License

[Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0)