OpenQASM 3 (qiskit.qasm3)

Qiskit provides some tools for converting between OpenQASM 3 representations of quantum programs, and the QuantumCircuit class. These will continue to evolve as Qiskit’s support for the dynamic-circuit capabilities expressed by OpenQASM 3 increases.

Exporting to OpenQASM 3

The high-level functions are simply dump() and dumps(), which respectively export to a file (given as a filename) and to a Python string.

dump(circuit, stream, **kwargs)[source]

Serialize a QuantumCircuit object as a OpenQASM3 stream to file-like object.

  • circuit (QuantumCircuit) – Circuit to serialize.

  • stream (TextIOBase) – stream-like object to dump the OpenQASM3 serialization

  • **kwargs – Arguments for the Exporter constructor.

Return type


dumps(circuit, **kwargs)[source]

Serialize a QuantumCircuit object in an OpenQASM3 string.


The OpenQASM3 serialization

Return type


Both of these exporter functions are single-use wrappers around the main Exporter class. For more complex exporting needs, including dumping multiple circuits in a single session, it may be more convenient or faster to use the complete interface.

class Exporter(includes=('stdgates.inc',), basis_gates=('U',), disable_constants=False, alias_classical_registers=False, indent='  ')[source]

QASM3 exporter main class.

  • includes (Sequence[str]) – the filenames that should be emitted as includes. These files will be parsed for gates, and any objects dumped from this exporter will use those definitions where possible.

  • basis_gates (Sequence[str]) – the basic defined gate set of the backend.

  • disable_constants (bool) – if True, always emit floating-point constants for numeric parameter values. If False (the default), then values close to multiples of QASM 3 constants (pi, euler, and tau) will be emitted in terms of those constants instead, potentially improving accuracy in the output.

  • alias_classical_registers (bool) – If True, then classical bit and classical register declarations will look similar to quantum declarations, where the whole set of bits will be declared in a flat array, and the registers will just be aliases to collections of these bits. This is inefficient for running OpenQASM 3 programs, however, and may not be well supported on backends. Instead, the default behaviour of False means that individual classical registers will gain their own bit[size] register; declarations, and loose Clbits will go onto their own declaration. In this form, each Clbit must be in either zero or one ClassicalRegisters.

  • indent (str) – the indentation string to use for each level within an indented block. Can be set to the empty string to disable indentation.

dump(circuit, stream)[source]

Convert the circuit to QASM 3, dumping the result to a file or text stream.


Convert the circuit to QASM 3, returning the result as a string.

All of these interfaces will raise QASM3ExporterError on failure.

exception QASM3ExporterError(*message)[source]

An error raised during running the OpenQASM 3 exporter.

Set the error message.

Importing from OpenQASM 3

Currently only two high-level functions are offered, as Qiskit support for importing from OpenQASM 3 is in its infancy, and the implementation is expected to change significantly. The two functions are load() and loads(), which are direct counterparts of dump() and dumps(), respectively loading a program indirectly from a named file and directly from a given string.


While we are still in the exploratory release period, to use either function, the package qiskit_qasm3_import must be installed. This can be done by installing Qiskit Terra with the qasm3-import extra, such as by:

pip install qiskit-terra[qasm3-import]

We expect that this functionality will eventually be merged into core Terra, and no longer require an optional import, but we do not yet have a timeline for this.


Load an OpenQASM 3 program from the file filename.


filename (str) – the filename to load the program from.


a circuit representation of the OpenQASM 3 program.

Return type



QASM3ImporterError – if the OpenQASM 3 file is invalid, or cannot be represented by a QuantumCircuit.


Load an OpenQASM 3 program from the given string.


program (str) – the OpenQASM 3 program.


a circuit representation of the OpenQASM 3 program.

Return type



QASM3ImporterError – if the OpenQASM 3 file is invalid, or cannot be represented by a QuantumCircuit.

Both of these two functions raise QASM3ImporterError on failure.

exception QASM3ImporterError(*message)[source]

An error raised during the OpenQASM 3 importer.

Set the error message.

For example, we can define a quantum program using OpenQASM 3, and use loads() to directly convert it into a QuantumCircuit:

import qiskit.qasm3

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

    input float[64] a;
    qubit[3] q;
    bit[2] mid;
    bit[3] out;

    let aliased = q[0:1];

    gate my_gate(a) c, t {
      gphase(a / 2);
      ry(a) c;
      cx c, t;
    gate my_phase(a) c {
      ctrl @ inv @ gphase(a) c;

    my_gate(a * 2) aliased[0], q[{1, 2}][0];
    measure q[0] -> mid[0];
    measure q[1] -> mid[1];

    while (mid == "00") {
      reset q[0];
      reset q[1];
      my_gate(a) q[0], q[1];
      my_phase(a - pi/2) q[1];
      mid[0] = measure q[0];
      mid[1] = measure q[1];

    if (mid[0]) {
      let inner_alias = q[{0, 1}];
      reset inner_alias;

    out = measure q;
circuit = qiskit.qasm3.loads(program)

(Source code)