Cirq: Google’s Python Library for Quantum Circuits

Cirq is an open-source Python framework from Google Quantum AI for creating, editing and running quantum circuits on simulators and hardware. Its repository describes it as a framework for “Noisy Intermediate-Scale Quantum (NISQ) circuits” and licenses it under Apache-2.0. This guide is for researchers who need to install Cirq, run a first circuit, read the output correctly and record the setup so the result can be reproduced.

What Cirq is used for in research

Cirq lets you describe a circuit as Python objects (qubits, gates, measurements), run it on a built-in simulator, and model devices and noise. The project ships as several packages: cirq-core plus integrations such as cirq-google, cirq-aqt, cirq-ionq, cirq-pasqal and cirq-web. For the underlying concept, see Quantum Circuit: Build, Draw and Read One in Qiskit and PennyLane.

Install or access (official source only)

The Google Quantum AI install page states that Cirq currently supports Python 3.11 and later (read 2026-11-08). It also advises installing into a virtual environment. If you manage environments with conda, see Install Anaconda Python and Sharing a Reproducible Conda Environment.

1. Update pip: python -m pip install --upgrade pip
2. Install Cirq: python -m pip install cirq
3. Optional extras: python -m pip install 'cirq-core[contrib]'
4. Verify the install: python -c 'import cirq_google; print(cirq_google.Sycamore)'. On Windows the official page uses double quotes around the Python code. A successful run prints the qubit layout diagram of the Sycamore device.

Step by step: build and run a Bell-state circuit

This follows the Cirq basics tutorial (quantumai.google/cirq/start/basics, read 2026-11-08).

1. Create qubits. Options include cirq.NamedQubit('source'), cirq.LineQubit(3), q0, q1, q2 = cirq.LineQubit.range(3) and cirq.GridQubit(4, 5).
2. Build the circuit. bell_circuit = cirq.Circuit(), then bell_circuit.append(cirq.H(q0)), bell_circuit.append(cirq.CNOT(q0, q1)) and bell_circuit.append(cirq.measure(q0, q1, key='result')).
3. Create a simulator. s = cirq.Simulator()
4. Inspect the state. results = s.simulate(bell_circuit) returns the full wave function; for the Bell state the tutorial shows 0.707|00> + 0.707|11>.
5. Sample the circuit. samples = s.run(bell_circuit, repetitions=1000)
6. Count outcomes. counts = samples.histogram(key='result') then print(counts). To plot, use cirq.plot_state_histogram(counts, plt.subplot()) with matplotlib imported as plt.

Output and how to read it

simulate versus run

simulate() returns the simulated state itself (the wave function). run() returns repeated measurement samples, the way hardware reports results. Report sampled results, not the wave function, when your claim is about what an experiment would return.

Histogram keys are integers

The histogram is a Counter keyed by integers that encode the measured bitstring. The tutorial’s example output, Counter({0: 516, 3: 484}), reads as key 0 = bitstring 00 and key 3 = bitstring 11. Counts vary from run to run, so do not expect the same 516/484 split; for a Bell state expect only 00 and 11, in roughly equal numbers.

Reproducibility checklist for a Cirq analysis

This is editorial guidance built on the project’s own citation advice: the Cirq repository asks users to cite the version they used and archives releases on Zenodo (concept DOI 10.5281/zenodo.4062499). See Zenodo: The CERN and OpenAIRE General-Purpose Research Repository and computational reproducibility.

• Record the Cirq version (python -m pip show cirq) and Python version.
• Record the number of repetitions passed to run().
• Archive the script or notebook with a license; see Open Source License.

Troubleshooting

• Install fails or wrong version resolves. Check python --version; Cirq requires Python 3.11 or later. Use a virtual environment and run pip as python -m pip so it matches the interpreter.
• Verification command errors on Windows. Use double quotes around the Python code, as the official page does.
• PDF circuit output fails. The install page lists a LaTeX requirement: brew install --cask mactex on macOS and the texlive-latex-base package on Linux.
• Different counts each run. This is expected for sampling; see above.

Free alternatives

Descriptions are from each project’s GitHub repository, read 2026-11-08.

Framework	Repository description	License
Cirq	Python framework for creating, editing and running NISQ circuits	Apache-2.0
Qiskit	Open-source SDK for working with quantum computers at the level of extended quantum circuits, operators and primitives (see IBM Quantum Platform guide)	Apache-2.0
PennyLane	Open-source quantum software platform for quantum computing, quantum machine learning and quantum chemistry	Apache-2.0

FAQ

What is Cirq?

A Python framework for creating, editing and running NISQ quantum circuits, developed under the quantumlib organization on GitHub and documented by Google Quantum AI.

Which Python version does Cirq need?

Python 3.11 or later, per the install page checked 2026-11-08.

How do I cite Cirq?

The repository directs users to cite the version they used; releases are archived on Zenodo under DOI 10.5281/zenodo.4062499.

Sources

• Google Quantum AI, Install Cirq: https://quantumai.google/cirq/start/install (read 2026-11-08)
• Google Quantum AI, Cirq basics: https://quantumai.google/cirq/start/basics (read 2026-11-08)
• Cirq repository: https://github.com/quantumlib/Cirq (read 2026-11-08)
• Qiskit repository: https://github.com/Qiskit/qiskit; PennyLane repository: https://github.com/PennyLaneAI/pennylane (read 2026-11-08)