Install & Compatibility
Where this runs
tested against v2.18.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 26.83s
py 3.11
✕ build_error
✓ 25.65s
py 3.12
✕ build_error
✓ 25.48s
py 3.13
✕ build_error
✓ 25.85s
py 3.9
✕ build_error
3/4 runs
886MB installed
● package 886MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Circuit
✓ from pytket import Circuit
The primary class for building and manipulating quantum circuits.
OpType
✓ from pytket.circuit import OpType
Used to specify a wide variety of quantum operations.
Transform
✓ from pytket.transform import Transform
Provides access to circuit transformation and optimization passes.
AerBackend
✓ from pytket.extensions.qiskit import AerBackend
Example of importing a backend from an extension module. Extension modules (e.g., pytket-qiskit) must be installed separately.
This quickstart demonstrates how to create a simple Bell state circuit, compile it using a Qiskit Aer simulator backend (requires `pytket-qiskit`), and then execute it to retrieve measurement counts. This illustrates the basic workflow of circuit construction, compilation, and execution.
from pytket import Circuit
from pytket.extensions.qiskit import AerBackend
# 1. Create a quantum circuit (Bell state)
circ = Circuit(2) # 2 qubits
circ.H(0) # Hadamard on qubit 0
circ.CX(0, 1) # CNOT with control 0, target 1
# 2. Compile the circuit for a backend (using Qiskit Aer simulator for demonstration)
# Note: pytket-qiskit extension must be installed for AerBackend
backend = AerBackend()
compiled_circ = backend.get_compiled_circuit(circ)
# 3. Execute the circuit
# For real devices, this may involve authentication (e.g., IBMQ credentials)
# For local simulators, no special setup is typically needed.
# We'll run 100 shots and retrieve measurement counts.
handle = backend.process_circuit(compiled_circ, n_shots=100)
result = backend.get_result(handle)
print(f"Circuit: {circ}")
print(f"Compiled Circuit: {compiled_circ}")
print(f"Measurement counts: {result.get_counts()}")
Debug
Known issues
breakingMajor API changes occurred between pytket 0.x.y, 1.x.y, and 2.x.y. Code written for older major versions might not be compatible with newer ones.fixRefer to the official pytket user guide and changelog for migration instructions when upgrading major versions.
affects: 0.x.y -> 1.x.y, 1.x.y -> 2.x.y
breakingpytket versions 1.24.0 and above require Python 3.10 or higher. Older Python environments (e.g., 3.7, 3.8, 3.9) will only install older, incompatible versions of pytket.fixUpgrade your Python environment to 3.10 or newer before installing pytket. Ensure pip is also up-to-date (`pip install --upgrade pip`).
affects: pytket >= 1.24.0
gotchaQubit ordering conventions in pytket differ from some other quantum SDKs (e.g., Qiskit). Circuits that appear identical in their gate sequence might correspond to different unitary operations when converted or interpreted across libraries.fixBe aware of qubit ordering when converting circuits to/from other frameworks or when comparing results. Consult the documentation for specific extension modules (e.g., pytket-qiskit) regarding conversion specifics.
affects: All versions
gotchaMost pytket extensions (e.g., `pytket-qiskit`, `pytket-cirq`, `pytket-quantinuum`) are separate pip packages and must be installed explicitly in addition to the core `pytket` library. Attempting to import components from an uninstalled extension will result in an ImportError.fixInstall the necessary extension package using `pip install pytket-X` where `X` is the name of the extension (e.g., `pip install pytket-qiskit`).
affects: All versions
Errors
Common errors & fixes
ImportError: DLL load failed: The specified module could not be found.
This error, particularly on Windows with older Python versions (e.g., 3.7, 3.8), often indicates issues with underlying C++ dependencies that pytket relies on (e.g., related to the `pytket._tket.pauli` module).
fixEnsure you are using a supported Python version (>=3.10 for recent pytket versions). If the issue persists, consider using an official Python distribution or a virtual environment, and ensure all system dependencies are correctly installed. For M1 Macs, `brew install openblas` and `pip install scipy` first may be required.
RuntimeError: Cannot merge circuits as both contain unit: l[0].
This error occurs when attempting to compose two circuits using methods like `Circuit.append()` or the `*` operator, and both circuits contain `UnitID`s (qubits/bits) with the same names, leading to ambiguity in composition.
fixBefore merging, rename the `UnitID`s in one or both circuits to ensure they are distinct using `Circuit.rename_units()`. Alternatively, use `Circuit.add_circuit()` for subcircuit insertion if unit unification is not desired.
pip install pytket results in an outdated version, despite a newer version being on PyPI.
Your current Python environment or `pip` version does not meet the minimum requirements of the latest `pytket` release (e.g., Python < 3.10 for pytket >= 1.24.0, or an old `pip` version).
fixFirst, upgrade `pip`: `pip install --upgrade pip`. Then, ensure your Python version meets the `pytket` requirements (>=3.10 for current versions). Upgrade Python if necessary.
The `pytket.extensions.qiskit.PlacementPass` on a `SquareGrid` architecture causes `RuntimeError` when running on `AerBackend`.
This is a known, currently open issue specific to certain combinations of placement passes and backend configurations within the `pytket-qiskit` extension.
fixCheck the `pytket-qiskit` GitHub issues or documentation for updates on this specific bug. As a workaround, try using a different placement pass, or a different backend for compilation/simulation if possible.
Upgrade
Version history
2.18.0latest on PyPI · released May 15, 2026
Audit
Dependencies
Python 3.10+requiredRequired for pytket versions >= 1.24.0. Older Python versions will install older pytket versions.
pytket-qiskitoptionalFor integration with Qiskit, including conversion and backend access.
pytket-cirqoptionalFor integration with Cirq, including conversion and backend access.
pytket-quantinuumoptionalFor integration with Quantinuum devices and simulators.