Serialization

---
name: serialization
description: "Guides agents importing, exporting, and troubleshooting Qiskit
  OpenQASM 2, OpenQASM 3, and QPY serialization workflows."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Qiskit serialization workflows

Use this sub-skill when the task involves `qiskit.qasm2`, `qiskit.qasm3`, or `qiskit.qpy`: reading or writing circuits, choosing interchange formats, preserving circuit structure, or debugging parser/exporter/version errors.

## Read next

- `references/workflows.md` for QASM2, QASM3, and QPY recipes.
- `references/troubleshooting.md` for missing `qiskit_qasm3_import`, parse/export errors, unsupported features, and legacy QPY compatibility.
- `../../references/installation.md` for the `qasm3-import` and `qpy-compat` extras.
- `../../scripts/check_qiskit_environment.py --sections serialization` for a source-free serialization smoke check.

## Include here

- `qiskit.qasm2.load`, `loads`, `dump`, `dumps`, custom instructions, custom classical functions, and strict mode.
- `qiskit.qasm3.load`, `loads`, `dump`, `dumps`, `Exporter`, experimental features, and native experimental parser entry points.
- `qiskit.qpy.dump`, `load`, `get_qpy_version`, QPY target versions, and compatibility limitations.
- Choosing between text interchange and full-fidelity binary circuit persistence.

## Exclude or route elsewhere

- Constructing the circuit before serialization belongs in `../circuit/SKILL.md`.
- Running or sampling the circuit belongs in `../primitives/SKILL.md` or `../providers/SKILL.md`.
- Matrix/state equivalence after deserialization belongs in `../quantum-info/SKILL.md`.
- Rendering a circuit to an image belongs in `../visualization/SKILL.md`.

## Default route

Start here when the user names QASM, OpenQASM, QPY, `load`, `loads`, `dump`, `dumps`, `QASM2ParseError`, `QASM3ImporterError`, `QASM3ExporterError`, `QpyError`, or `UnsupportedFeatureForVersion`.

## What to remember

- OpenQASM 2 is useful but cannot represent the full Qiskit circuit model.
- OpenQASM 3 is the modern text path; import via `qasm3.load()`/`loads()` needs the optional importer for the compatibility path.
- QPY is the highest-fidelity Qiskit circuit persistence format, but version compatibility and legacy `symengine` choices matter.