Cirq: a Python framework for NISQ circuits, from gate definition to hardware

What Cirq solves, and who ends up using it

Most circuit libraries start from an idealized model: qubits are interchangeable, gates are perfect, and the only thing that matters is the gate sequence. Cirq starts from the opposite end. The README describes it as providing "useful abstractions for dealing with today's noisy intermediate-scale quantum (NISQ) computers, where the details of quantum hardware are vital to achieving state-of-the-art results." That sentence is the whole design brief.

So the audience is narrower than "anyone learning quantum computing". It is people who need to say which physical qubit a gate acts on, what the device's connectivity looks like, and how noise enters the computation. The repository layout reflects this: cirq-core holds the framework, while cirq-google, cirq-ionq and cirq-pasqal are separate packages for specific hardware backends. If you only want to run a textbook algorithm on a simulator, you are using a fraction of what is installed.

The feature list in the README is a fair summary of the surface area: flexible gate definitions and custom gates, parameterized circuits with symbolic variables, circuit transformation and compilation, hardware device modeling, noise modeling, multiple built-in simulators, and interoperability with NumPy and SciPy. Each of those is a distinct subsystem, not a bullet point on a marketing page.

How a Cirq program is structured: qubits, moments, operations

The quick start example is short enough to read as the architecture. A cirq.GridQubit(0, 0) names a position on a two-dimensional grid, so a qubit is an addressable object rather than an index. Operations are created by calling gate objects such as cirq.X(qubit) and cirq.measure(qubit, key='m'), and a Circuit is constructed from a sequence of them.

The printed circuit in the README shows the layout convention:

(0, 0): ───X^0.5───M('m')───

Each row is one qubit, and the horizontal position is the moment, Cirq's term for a time slice. Gates that commute can share a moment; gates that do not are pushed into later ones. This is why the framework can optimize and transform circuits at all: the moment structure makes parallelism and dependency explicit rather than leaving them implicit in a flat list of instructions.

Execution goes through a simulator object. The example builds cirq.Simulator() and calls run(circuit, repetitions=20), which returns measurement results keyed by the string passed to measure. That key is how classical data comes back out of the quantum program, and it is the same mechanism you would use against real hardware. The README shows the result as a bitstring such as m=11000111111011001000.

Installing Cirq and running the hello qubit example

The README states that Cirq supports Python 3.11 and later, on Linux, macOS and Windows, as well as Google Colab, and directs readers to the Install section of the online documentation at quantumai.google/cirq/start/install for complete instructions. The reference documentation notes that the current stable release corresponds to what you get with pip install cirq, and that a pre-release is available with pip install --upgrade cirq~=1.0.dev.

The package is published on PyPI, so the standard install is a single command:

pip install cirq

That installs the metapackage. The repository's setup.py describes cirq as "a pure metapackage that installs all our packages", pulling in cirq-core plus the hardware integration packages at pinned versions. If you want only the framework, the README's reference section points at cirq-core as the separately installable base, and the contrib extras are exposed as cirq-core[contrib].

Once installed, the README's quick start is the first real use. It creates a circuit with a square-root-of-NOT gate and a measurement, prints the circuit, then simulates it twenty times:

import cirq

qubit = cirq.GridQubit(0, 0)

circuit = cirq.Circuit(
    cirq.X(qubit)**0.5,
    cirq.measure(qubit, key='m')
)
print("Circuit:")
print(circuit)

simulator = cirq.Simulator()
result = simulator.run(circuit, repetitions=20)
print("Results:")
print(result)

The output you should see is a one-line diagram of the circuit followed by twenty measurement outcomes. Because X**0.5 puts the qubit in an equal superposition, the bitstring should look like a random mix of zeros and ones rather than a fixed pattern. If you get all zeros or all ones across many repetitions, something is wrong with the circuit construction, not with the simulator.

Where Cirq stops being the right tool

Cirq's abstractions are tied to NISQ devices, and that is a real boundary. The README's own integration table is the clearest statement of it. For fault-tolerant quantum computing and quantum algorithms, it points to Qualtran. For circuits with thousands of qubits and millions of Clifford operations, and for quantum error correction, it points to Stim. For large circuits and heavy simulation workloads, it points to qsim.

Read that table as a list of things Cirq is not optimized for. A Clifford-dominated workload with thousands of qubits is exactly the case where a state-vector simulator becomes impractical, and Cirq's built-in simulators are not presented as the answer there. Likewise, if your goal is to express a fault-tolerant algorithm at the level of logical operations and resource counts, the NISQ gate-and-moment model is the wrong layer.

There is a second, quieter limitation: the moment-based circuit model forces a scheduling decision at construction time. Gates that could be parallelized must be placed in a way the circuit builder recognizes as parallel. For circuits with irregular connectivity, this means you spend effort on layout and alignment, which is the point of the framework but also the cost of it.

A third constraint is packaging. Because cirq is a metapackage that installs all the integration packages, a plain pip install cirq brings in backend code for hardware you may never touch. The README does not document an uninstall or slimming path for that; if dependency weight matters, installing cirq-core directly is the route the documentation implies.

Cirq versus Qiskit: two different starting assumptions

The comparison people search for is Cirq versus Qiskit, and the difference is not a feature checklist. Both are Python SDKs for building and running quantum circuits. The divergence is in what the core object assumes.

Cirq's core object is a circuit over explicitly addressed qubits, with moments as time slices and device objects that describe connectivity and noise. The README's feature list puts hardware device modeling and noise modeling alongside gate definitions, which tells you these are first-class concerns rather than add-ons.

Qiskit's approach centers on a circuit built against a backend abstraction, with transpilation as the stage that maps your logical circuit onto real hardware. The practical consequence: in Cirq you tend to write circuits with the target device's shape in mind from the start, while in a transpiler-centric workflow you write something closer to hardware-agnostic and let the toolchain rewrite it. Neither is strictly better. If your research depends on controlling exactly which physical qubit carries which gate, Cirq's model is more direct. If you want to write once and retarget across providers, a transpilation-first stack asks less of you.

Cirq's own integration table reinforces the point: rather than trying to cover every workload, it delegates fault-tolerant algorithm expression, large-scale Clifford simulation, error correction and chemistry to separate projects in the same family.

Maintenance, release cadence and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-22, one day before the date used for this assessment. The release history shows v1.7.0 on 2026-06-30, v1.6.1 on 2025-08-14 and v1.6.0 on 2025-07-23. That is a steady line of tagged releases rather than a burst, with roughly a year between the 1.6 and 1.7 minor versions and a patch release in between.

The upgrade cost is mostly about the metapackage. setup.py pins each subpackage to the same version as the metapackage itself, so upgrading cirq moves cirq-core and every integration package together. If you depend on cirq-google, cirq-ionq or cirq-pasqal directly, you should expect to move them in lockstep with the metapackage rather than independently. The README also distinguishes stable from pre-release documentation, with the pre-release installed via pip install --upgrade cirq~=1.0.dev, so you can track unreleased changes if you need to, at the cost of running ahead of the documented stable reference.

On licensing: the project is Apache-2.0, and the README carries the badge and links the LICENSE file. The setup.py header reproduces the standard Apache 2.0 notice. Apache-2.0 is a permissive licence with an explicit patent grant, which matters for a library that may end up in commercial quantum software. This is a description of the licence text, not legal advice; if you are redistributing Cirq inside a product, read the LICENSE file in the repository rather than a summary.

Editorial conclusion

Adopt Cirq if your work depends on the physical layout of a device, custom gate definitions, or noise models, and you are on Python 3.11 or later. Do not adopt it expecting a hardware-neutral intermediate representation; Cirq's abstractions are built around NISQ devices, and the README points to Qualtran for fault-tolerant algorithm work, Stim for large Clifford circuits, and qsim when simulation scale is the bottleneck. Before committing, check the install page at quantumai.google/cirq/start/install for the current dependency set and confirm which of the cirq-google, cirq-ionq or cirq-pasqal packages matches the hardware you can actually submit to.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. quantumlib/Cirq on GitHub
4. README
5. Releases