Qiskit Transpilation Explained: Optimize Quantum Circuits for Real Hardware
Transpilation converts a hardware-independent quantum circuit into instructions that a selected quantum processor can execute. This Qiskit transpiler tutorial shows how to choose a target, inspect basis gates and connectivity, compare optimization levels, evaluate layout and routing, and track the resource changes that matter before submitting a job.
Overview
A circuit written with familiar operations such as h, cx, and measure is usually not ready for a particular quantum device. Real processors expose a limited instruction set, a physical-qubit topology, calibration-dependent performance, and execution constraints. Transpilation is the compilation stage that adapts the circuit to those conditions.
In Qiskit, the central entry point is commonly qiskit.transpile(). It can accept a backend or a target description and return a circuit expressed in supported operations and physical-qubit assignments. A typical workflow looks like this:
from qiskit import QuantumCircuit, transpile
circuit = QuantumCircuit(3, 3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.measure(range(3), range(3))
compiled = transpile(
circuit,
backend=backend,
optimization_level=2,
seed_transpiler=42
)The exact backend acquisition code depends on the provider and environment, so keep target selection separate from circuit construction. That makes it easier to compile the same logical circuit for a simulator, a local test target, and several hardware candidates.
Transpilation is not simply “make the circuit smaller.” It balances several goals: compatibility, circuit depth, two-qubit gate count, routing overhead, and sometimes compilation time. A circuit with fewer total instructions is not automatically better if it has more error-prone two-qubit operations or a worse physical layout.
What to track
Target and instruction set
Record the target used for every compiled circuit. If you pass a backend, Qiskit can use its target information, including supported operations and qubit connectivity. When working with newer workflows or custom targets, inspect the target directly where appropriate rather than assuming that every processor supports the same basis gates.
The basis gates are the operations the target can execute natively or accepts as its compilation boundary. Unsupported operations are decomposed into supported instructions. For example, a multi-qubit operation may become a sequence of one- and two-qubit gates. Save the target name or identifier, the relevant instruction set, and the date of compilation alongside benchmark results.
Depth and gate counts
Compare the logical circuit with the transpiled circuit using metrics that expose different costs:
Total instruction count: useful for seeing general expansion, but insufficient on its own.Circuit depth: indicates how many sequential layers must execute.Two-qubit gate count: often a particularly important hardware-aware metric because entangling operations can be more demanding than single-qubit operations.Operation breakdown: shows whether optimization replaced one gate pattern with another and whether routing inserted extra swaps or controlled operations.Qubit usage: confirms the number of physical qubits occupied after layout.
In code, basic inspection can start with:
print("depth:", compiled.depth())
print("size:", compiled.size())
print("operations:", compiled.count_ops())
print(compiled.draw(output="text"))
For a more complete record, store these values as structured data rather than copying them from a circuit diagram. This makes repeated comparisons easier when a circuit or target changes.
Layout and routing
A logical circuit describes relationships between abstract qubits. A hardware device connects physical qubits in a particular topology. Layout assigns logical qubits to physical qubits; routing resolves interactions that are not directly supported by that assignment, often by inserting swaps or equivalent gate sequences.
Routing can dominate the final circuit. A compact logical circuit may become substantially deeper when its interacting qubits are far apart on the coupling map. Track the number of added operations and inspect the final layout when comparing strategies. If you supply an initial layout, treat it as a hypothesis to benchmark, not as a guaranteed improvement.
Optimization settings
Qiskit exposes optimization levels that provide convenient presets. Their detailed behavior can change with SDK releases and target configuration, so treat the level as a starting point and inspect the output rather than relying on its label alone.
| Setting | Useful starting point | Trade-off to check |
|---|---|---|
optimization_level=0 | Debugging, baseline comparisons, and checking basic target compatibility | May leave substantial decomposition or routing overhead |
optimization_level=1 | Quick iterative development and simple circuits | May sacrifice some reductions for shorter compilation |
optimization_level=2 | Routine experiments where circuit quality and compile time both matter | Compare depth and two-qubit counts against the baseline |
optimization_level=3 | Final candidates where additional compilation effort is acceptable | Compilation can take longer, and the result still requires validation |
Use the same input circuit, target, and random seed when comparing levels. A fixed seed_transpiler can improve reproducibility during a test, although it does not make a circuit permanently optimal.
Pass managers for controlled workflows
Preset optimization levels are convenient, but a Qiskit pass manager gives you more control over stages such as layout, routing, translation, and optimization. The builder APIs and pass names should be checked against the Qiskit version installed in your environment. A version-aware pattern is to construct a preset pass manager for a target and then run it:
from qiskit.transpiler import generate_preset_pass_manager
pm = generate_preset_pass_manager(
optimization_level=2,
backend=backend
)
compiled = pm.run(circuit)
Custom pass pipelines are useful when you need to compare layout methods, preserve a particular structure, or insert analysis and validation steps. Keep custom pipelines small and documented. A pipeline that improves one circuit family may perform poorly on another.
Cadence and checkpoints
Transpilation results are target-dependent, so review them whenever the target, circuit, or software environment changes. For an active project, a monthly or quarterly checkpoint is a practical minimum even when the logical circuit appears unchanged.
At circuit creation: record the logical depth, operation counts, number of qubits, and expected interaction pattern.When choosing a backend: confirm supported operations, connectivity, available qubits, and any execution constraints exposed by the provider.Before a benchmark: transpile with a fixed target and documented settings. Save the compiled circuit or a reproducible representation of it.After SDK or provider changes: rerun the same compilation comparison. Preset passes, target metadata, and provider terminology may evolve.Before production-style runs: compare at least one baseline with the selected optimization and layout strategy, then record depth, two-qubit count, and qubit mapping.
Pair this review with a measurement plan. The quantum circuit benchmarking guide provides a broader framework for comparing depth, fidelity, runtime, and error-related behavior. For cost and execution planning, see the quantum resource estimation guide.
How to interpret changes
If optimization reduces depth without increasing two-qubit operations, that is often a useful result, but it is not a complete performance conclusion. If depth rises while two-qubit count falls, the trade-off may still be favorable depending on the device and algorithm. If both rise, inspect layout and routing first.
A large difference between logical and transpiled depth usually indicates one of three issues: the circuit uses operations outside the target basis, the logical interaction graph conflicts with hardware connectivity, or the selected layout does not place frequently interacting qubits near one another. Try a different layout strategy or provide a tested initial layout, then compare the same metrics.
Do not compare circuits compiled for different targets as if their raw gate counts had identical meaning. A target may use different native operations, coupling directions, or decomposition choices. Treat each comparison as hardware-specific and include target metadata in your results.
Transpilation also does not remove physical noise. If the compiled circuit remains sensitive to errors, consider measurement and error-mitigation techniques separately; the error mitigation overview explains the related trade-offs. Transpilation and mitigation address different stages of the workflow.
When to revisit
Revisit this workflow when you move to a new backend, change the circuit’s entanglement pattern, add measurements, or alter the target basis. Also repeat the comparison after a Qiskit upgrade, provider integration change, or substantial pass-manager modification. These events can change the available target description or the compiled structure even when the source circuit is identical.
For a practical recurring review, keep a small compilation report containing:
source-circuit identifier and logical resource counts;target or backend identifier;Qiskit and provider environment details;optimization level or pass-manager configuration;seed, initial layout, and routing choices;transpiled depth, total operations, two-qubit count, and final layout;observed benchmark results, if the circuit was executed.
Start with transpile() and a baseline at optimization level 0, compare levels 1 through 3 using the same target, and only then introduce custom passes or layouts. If the selected configuration wins on your recorded metrics and remains stable across representative circuits, preserve it as a reproducible workflow. When it does not, return to the target, layout, and routing assumptions rather than assuming that a higher optimization level is the answer.
For the next step, compare the same circuit across two candidate backends using the checklist in How to Choose the Right Quantum Backend. The goal is not to find one universally best transpilation setting. It is to make the compilation decision visible, measurable, and easy to revisit as your circuit and hardware targets change.