---
title: compiler (latest version)
description: API reference for qiskit.compiler in the latest version of qiskit
source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit/compiler
---

# Compilation Routines

`qiskit.compiler`

## Circuit Compilation Functions

### transpile

`qiskit.compiler.transpile(circuits, backend=None, basis_gates=None, coupling_map=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, dt=None, approximation_degree=1.0, seed_transpiler=None, optimization_level=None, callback=None, output_name=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, target=None, hls_config=None, init_method=None, optimization_method=None, ignore_backend_supplied_default_methods=False, num_processes=None, qubits_initially_zero=True)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/compiler/transpiler.py#L38-L322)

Transpile one or more circuits, according to some desired transpilation targets.

Transpilation is potentially done in parallel using multiprocessing when `circuits` is a list with > 1 [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object, depending on the local environment and configuration.

The prioritization of transpilation target constraints works as follows: if a `target` input is provided, it will take priority over any `backend` input or loose constraints (`basis_gates`, `coupling_map`, or `dt`). If a `backend` is provided together with any loose constraint from the list above, the loose constraint will take priority over the corresponding backend constraint. This behavior is summarized in the table below. The first column in the table summarizes the potential user-provided constraints, and each cell shows whether the priority is assigned to that specific constraint input or another input (target/backend(V2)).

| User Provided     | target | backend(V2)   |
| ----------------- | ------ | ------------- |
| **basis\_gates**  | target | basis\_gates  |
| **coupling\_map** | target | coupling\_map |
| **dt**            | target | dt            |

> **Note**
>
> When the target basis consists of Clifford+T gates, this function constructs a specialized Clifford+T transpiler pipeline, see [`generate_preset_clifford_t_pass_manager()`](/docs/api/qiskit/qiskit.transpiler.generate_preset_clifford_t_pass_manager "qiskit.transpiler.generate_preset_clifford_t_pass_manager") for more detailed documentation. Arguments that apply only to transpiling into continuous basis sets are ignored in this flow. For example, the `"unitary_synthesis_method"` is not taken into account when synthesizing single-qubit unitaries into a Clifford+T sequence.

**Parameters**

- **circuits** (*\_CircuitT*) – Circuit(s) to transpile

- **backend** ([*Backend*](/docs/api/qiskit/qiskit.providers.Backend "qiskit.providers.backend.Backend") *| None*) – If set, the transpiler will compile the input circuit to this target device. If any other option is explicitly set (e.g., `coupling_map`), it will override the backend’s.

- **basis\_gates** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*] | None*) – List of basis gate names to unroll to (e.g.: `['u1', 'u2', 'u3', 'cx']`). If `None`, do not unroll.

- **coupling\_map** ([*CouplingMap*](/docs/api/qiskit/qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap")  *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*]] | None*) –

  Directed coupling map (perhaps custom) to target in mapping. If the coupling map is symmetric, both directions need to be specified.

  Multiple formats are supported:

  1. `CouplingMap` instance
  2. List, must be given as an adjacency matrix, where each entry specifies all directed two-qubit interactions supported by backend, e.g.: `[[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]]`

- **initial\_layout** ([*Layout*](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout")  *|*[*dict*](https://docs.python.org/3/library/stdtypes.html#dict)  *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list) *| None*) –

  Initial position of virtual qubits on physical qubits. If this layout makes the circuit compatible with the coupling\_map constraints, it will be used. The final layout is not guaranteed to be the same, as the transpiler may permute qubits through swaps or other means. Multiple formats are supported:

  1. `Layout` instance

  2. Dict \* virtual to physical:

     ```python
     {qr[0]: 0,
      qr[1]: 3,
      qr[2]: 5}
     ```

     - physical to virtual:

       ```python
       {0: qr[0],
        3: qr[1],
        5: qr[2]}
       ```

  3. List

     - virtual to physical:

       ```python
       [0, 3, 5]  # virtual qubits are ordered (in addition to named)
       ```

     - physical to virtual:

       ```python
       [qr[0], None, None, qr[1], None, qr[2]]
       ```

- **layout\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str) *| None*) – Name of layout selection pass (‘trivial’, ‘dense’, ‘sabre’). This can also be the external plugin name to use for the `layout` stage. You can see a list of installed plugins by using [`list_stage_plugins()`](/docs/api/qiskit/transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"layout"` for the `stage_name` argument.

- **routing\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str) *| None*) – Name of routing pass (‘basic’, ‘lookahead’, ‘stochastic’, ‘sabre’, ‘none’). This can also be the external plugin name to use for the `routing` stage. You can see a list of installed plugins by using [`list_stage_plugins()`](/docs/api/qiskit/transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"routing"` for the `stage_name` argument.

- **translation\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str) *| None*) – Name of translation pass (`"default"`, `"translator"` or `"synthesis"`). This can also be the external plugin name to use for the `translation` stage. You can see a list of installed plugins by using [`list_stage_plugins()`](/docs/api/qiskit/transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"translation"` for the `stage_name` argument.

- **scheduling\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str) *| None*) – Name of scheduling pass. \* `'as_soon_as_possible'`: Schedule instructions greedily, as early as possible on a qubit resource. (alias: `'asap'`) \* `'as_late_as_possible'`: Schedule instructions late, i.e. keeping qubits in the ground state when possible. (alias: `'alap'`) If `None`, no scheduling will be done. This can also be the external plugin name to use for the `scheduling` stage. You can see a list of installed plugins by using [`list_stage_plugins()`](/docs/api/qiskit/transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"scheduling"` for the `stage_name` argument.

- **dt** ([*float*](https://docs.python.org/3/library/functions.html#float) *| None*) – Backend sample time (resolution) in seconds. If `None` (default), `backend.dt` is used.

- **approximation\_degree** ([*float*](https://docs.python.org/3/library/functions.html#float) *| None*) – Heuristic dial used for circuit approximation, where `1.0` means no approximation (up to numerical tolerance) and `0.0` means the maximum approximation. If `target` is available, a value of `None` indicates that approximation is allowed up to the reported error rate for an operation in the target.

- **seed\_transpiler** ([*int*](https://docs.python.org/3/library/functions.html#int) *| None*) – Sets a seed for the PRNG used by the stochastic parts of the transpiler. This parameter takes precedence over the `QISKIT_TRANSPILER_SEED` environment variable and `transpiler_seed` setting in the user configuration file .

- **optimization\_level** ([*int*](https://docs.python.org/3/library/functions.html#int) *| None*) –

  How much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer transpilation time.

  - 0: no optimization
  - 1: light optimization
  - 2: heavy optimization
  - 3: even heavier optimization

  If `None`, level 2 will be chosen as default.

- **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)*\[\[BasePass,* [*DAGCircuit*](/docs/api/qiskit/qiskit.dagcircuit.DAGCircuit "qiskit._accelerate.circuit.DAGCircuit")*,* [*float*](https://docs.python.org/3/library/functions.html#float)*,* [*PropertySet*](/docs/api/qiskit/qiskit.passmanager.PropertySet "qiskit.passmanager.compilation_status.PropertySet")*,* [*int*](https://docs.python.org/3/library/functions.html#int)*],* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any)*] | None*) –

  A callback function that will be called after each pass execution. The function will be called with 5 keyword arguments, | `pass_`: the pass being run. | `dag`: the dag output of the pass. | `time`: the time to execute the pass. | `property_set`: the property set. | `count`: the index for the pass execution. The exact arguments passed expose the internals of the pass manager, and are subject to change as the pass manager internals change. If you intend to reuse a callback function over multiple releases, be sure to check that the arguments being passed are the same. To use the callback feature, define a function that will take in kwargs dict and access the variables. For example:

  ```python
  def callback_func(**kwargs):
      pass_ = kwargs['pass_']
      dag = kwargs['dag']
      time = kwargs['time']
      property_set = kwargs['property_set']
      count = kwargs['count']
      ...
  transpile(circ, callback=callback_func)
  ```

- **output\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)  *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*] | None*) – A list with strings to identify the output circuits. The length of the list should be exactly the length of the `circuits` parameter.

- **unitary\_synthesis\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – The name of the unitary synthesis method to use. By default `'default'` is used. You can see a list of installed plugins with [`unitary_synthesis_plugin_names()`](/docs/api/qiskit/qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names "qiskit.transpiler.passes.synthesis.plugin.unitary_synthesis_plugin_names").

- **unitary\_synthesis\_plugin\_config** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict) *| None*) – An optional configuration dictionary that will be passed directly to the unitary synthesis plugin. By default this setting will have no effect as the default unitary synthesis method does not take custom configuration. This should only be necessary when a unitary synthesis plugin is specified with the `unitary_synthesis_method` argument. As this is custom for each unitary synthesis plugin refer to the plugin documentation for how to use this option.

- **target** ([*Target*](/docs/api/qiskit/qiskit.transpiler.Target "qiskit.transpiler.target.Target") *| None*) – A backend transpiler target. Normally this is specified as part of the `backend` argument, but if you have manually constructed a [`Target`](/docs/api/qiskit/qiskit.transpiler.Target "qiskit.transpiler.Target") object you can specify it manually here. This will override the target from `backend`.

- **hls\_config** ([*HLSConfig*](/docs/api/qiskit/qiskit.transpiler.passes.HLSConfig "qiskit.transpiler.passes.synthesis.high_level_synthesis.HLSConfig") *| None*) – An optional configuration class `HLSConfig` that will be passed directly to `HighLevelSynthesis` transformation pass. This configuration class allows specifying the lists of synthesis algorithms and their parameters for various high-level objects.

- **init\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str) *| None*) – The plugin name to use for the `init` stage. By default an external plugin is not used. You can see a list of installed plugins by using [`list_stage_plugins()`](/docs/api/qiskit/transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"init"` for the stage name argument.

- **optimization\_method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str) *| None*) – The plugin name to use for the `optimization` stage. By default an external plugin is not used. You can see a list of installed plugins by using [`list_stage_plugins()`](/docs/api/qiskit/transpiler_plugins#qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins "qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins") with `"optimization"` for the `stage_name` argument.

- **ignore\_backend\_supplied\_default\_methods** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If set to `True` any default methods specified by a backend will be ignored. Some backends specify alternative default methods to support custom compilation target-specific passes/plugins which support backend-specific compilation techniques. If you’d prefer that these defaults were not used this option is used to disable those backend-specific defaults.

- **num\_processes** ([*int*](https://docs.python.org/3/library/functions.html#int) *| None*) – The maximum number of parallel processes to launch for this call to transpile if parallel execution is enabled. This argument overrides `num_processes` in the user configuration file, and the `QISKIT_NUM_PROCS` environment variable. If set to `None` the system default or local user configuration will be used.

- **qubits\_initially\_zero** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – Indicates whether the input circuit is zero-initialized.

**Returns**

The transpiled circuit(s).

**Raises**

[**TranspilerError**](/docs/api/qiskit/transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – in case of bad inputs to transpiler (like conflicting parameters) or errors in passes

**Return type**

*\_CircuitT*