pyzx: rewriting quantum circuits with the ZX-calculus

The unit of work is a diagram, not a gate list

PyZX is described as a Python tool implementing the theory of ZX-calculus for the creation, visualisation and automated rewriting of large-scale quantum circuits, and the pronunciation is given as *Pisics*. The theory behind it is what makes the library more than a circuit pretty-printer. ZX-diagrams are a type of tensor network built out of combinations of linear maps known as spiders, of which there are two kinds: Z-spiders, shown as green dots in PyZX, and X-spiders, shown as red dots. Every linear map between some set of qubits can be represented by a ZX-diagram. So a circuit is converted into a diagram, the diagram is rewritten by rules that preserve its meaning, and a circuit is extracted back out. The audience is a quantum software researcher or engineer who needs to reason about circuit structure symbolically rather than by inspecting a gate list.

Only the Clifford fragment is covered, and there the rule set is complete

The limitation in the README is stated precisely, and it is the most important technical fact for anyone deciding whether to use the library. PyZX uses only rewrite rules concerning the Clifford fragment of the ZX-calculus. Importantly, this set of rewrite rules is complete for Clifford diagrams, meaning that two representations of a Clifford map can be rewritten into one another if and only if the two linear maps they represent are equal. That completeness is a mathematical property rather than a benchmark claim, and it is what makes the reduced form a canonical answer rather than one particular reduction. The cost is scope: circuits that use non-Clifford gates sit outside what the rules can reason about. The README also notes that PyZX extensively uses two derived rewrite rules known as local complementation and pivoting.

The library reads quantum circuits in the file format of QASM, Quipper or Quantomatic, and outputs the optimised circuits in QASM, QC or QUIPPER format. Reading three formats is generous, but the Quantomatic reader is notable because Quantomatic is also one of the visualisation backends, so a circuit can round-trip from a diagram tool into PyZX and back out. The input side covers the formats produced by other toolchains, and the output side covers the formats most simulators and hardware pipelines consume. The in-browser demo at zxcalculus.com/pyzx.html shows some of these features without an install, which is the fastest way to judge whether the diagram model fits your workflow.

Installing with pip, and cloning when you want the demos

For use as a Python module inside other projects, the README recommends pip:

    pip install pyzx

If you want the demos or the benchmark circuits, the README says to install PyZX from source by cloning the git repository instead. PyZX has no strict dependencies, although some functionality requires numpy, and it is built to interact well with Jupyter, so the README additionally recommends having Jupyter and matplotlib installed. The packaging metadata is more specific than that. The project requires Python 3.11 or newer, is classified as Development Status 4 - Beta, and its runtime dependencies are typing_extensions, numpy, pyperclip, tqdm, ipywidgets and lark. The lark dependency is what parses the textual circuit formats, and ipywidgets is what makes the drawing work inside a notebook.

A five-qubit random circuit in nine lines of Python

The README's example generates a random circuit, optimises it, and draws it:

import pyzx as zx
qubit_amount = 5
gate_count = 80
#Generate random circuit of Clifford gates
circuit = zx.generate.cliffordT(qubit_amount, gate_count)
#If running in Jupyter, draw the circuit
zx.draw(circuit)
#Use one of the built-in rewriting strategies to simplify the circuit
zx.simplify.full_reduce(circuit)
#See the result
zx.draw(circuit)

The API shape is worth reading closely. `zx.generate.cliffordT` produces the circuit, `zx.draw` renders it, and `zx.simplify.full_reduce` runs a built-in rewriting strategy to simplify it, after which the same draw call shows the result. The comments in the sample are not decoration: they mark the two-phase flow, generate and draw, then reduce and draw again, and the second draw is how you see the effect of the rewrite. `full_reduce` is a convenience entry point that picks a simplification strategy for you, and the documentation at pyzx.readthedocs.io covers the built-in strategies if you want to choose one explicitly.

The command line entry point optimises a file in place of a script

PyZX can also be run from the command line, and the README gives one invocation for optimising a circuit:

python -m pyzx opt input_circuit.qasm

The module is invoked as `python -m pyzx` with the `opt` subcommand and a file argument, so there is no separate console script to install and no PATH entry to manage. The same command that the Python API performs is available for a one-off reduction in a build script or a CI job, which matters when the circuit file is produced by another tool and you want the reduced version as an artifact. The repository layout backs the rest of the toolchain: a `benchmark.py` at the root, a `circuits/` directory of test circuits, a `demos/` directory of Jupyter notebooks, `scratchpads/` for work in progress, and a `doc/` directory that the Sphinx configuration builds.

Visualisation goes through Matplotlib, Quantomatic or TikZ

The drawing side has three outputs, and the choice is about where the diagram ends up. PyZX can visualise the ZX-graphs and rewrites using either Matplotlib, Quantomatic, or as a TikZ file for use in LaTeX documents. That last option is the one that makes the library useful in a paper-writing workflow, since a TikZ file goes straight into a LaTeX document as vector artwork rather than a raster screenshot. The Matplotlib path is what the in-notebook `zx.draw` call uses, and Quantomatic output lets you carry the diagram into an interactive editor. The repository also ships images of the ZX-diagram notation, including the plane that says PYZX, and the demos folder contains demonstration notebooks that the README recommends if you have Jupyter installed.

Where pyzx is the wrong tool

Three limits are concrete. The first is the Clifford restriction, and it bites hardest on exactly the circuits people want to optimise, since the useful gates in near-term devices are often non-Clifford. A circuit with T gates will not be fully reduced. The second is the beta status and the moving target. The project is marked Development Status 4 - Beta, the version is 0.10.7, and the releases listed are monthly: v0.10.7 on 2026-10-01, v0.10.6 on 2026-09-01, and v0.10.5 on 2026-08-01, with the last push on 2026-10-20. A monthly release cadence on a 0.x version means the API can shift under you, and the Python floor of 3.11 or newer is itself recent. The third is the scope of what optimisation means. PyZX optimises the representation, not the depth of the circuit in terms of hardware gates, so a reduced ZX-diagram is not automatically a shallower circuit for a specific device, and the library does not target a particular gate set.

ZXLive is the alternative when you want to draw rather than script

The related project is ZXLive, and the difference in approach is interface rather than algorithm. ZXLive is an interactive graphical tool to draw, rewrite and experiment with ZX-diagrams, and the README says it is powered by PyZX under the hood. That means the rewrite rules and the diagram model are the same, and what changes is whether you drive them from Python or from a mouse. For a researcher exploring the theory, that is the faster loop. For a build pipeline or a test suite, a Python API is the right shape, and ZXLive would sit beside it rather than replace it. Outside this family, the ordinary alternative for circuit optimisation is a numeric gate-level optimiser, which works on the gate list with a cost function tied to a target device; the difference in approach is that pyzx reasons symbolically about the linear map, while a gate-level tool reasons numerically about a cost.

Editorial conclusion

pyzx fits a quantum software team that wants to shrink a circuit automatically rather than by hand, and that has circuits large enough that rewriting by hand is impractical. It is the wrong tool for circuits outside the Clifford fragment, because the rewrite rules PyZX uses concern only the Clifford fragment of the ZX-calculus. Before you adopt it, check the Python floor, since the package requires Python 3.11 or newer, and read the built-in simplification strategies in the documentation, since `zx.simplify.full_reduce` picks a strategy for you and a different choice can give a different final circuit.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. zxcalc/pyzx on GitHub