Cirq's pinned metapackage, its twenty shot quick start, and the nine projects its integrations table points to
Python framework for creating, editing, and running Noisy Intermediate-Scale Quantum (NISQ) circuits.
At a glance
- What is it?
- Cirq is an Apache-2.0 Python framework for NISQ circuits, distributed as a metapackage that pins its component packages to one version string. Its quick start is twenty local shots, and error correction and chemistry work live in other repositories.
- Who is it for?
- Cirq suits researchers who already know which device or simulator they care about and want a Python API with device and noise modeling instead of a black box. Before you install, read the Install section of the online documentation for anything other than a default platform, and check that your interpreter matches the pinned metapackage.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- quantumlib/Cirq5,105 ★ · +37
| Repository | 2026-09-23 | 2026-11-21 |
|---|---|---|
| quantumlib/Cirq | 5.1k | 5.1k |
37 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
One version string in cirq-core pins every vendor package
The root setup.py never types a version number. It runs cirq-core/cirq/_version.py through runpy, pulls the __version__ entry out of the resulting namespace, and asserts that the string is not empty. That single value then builds `requirements = [f'{p.name}=={p.version}' for p in modules.list_modules()]`, which means the distribution named cirq carries no code of its own. It is a metapackage whose dependency list is generated from the repository layout, and that layout is where the vendor code lives: cirq-core, cirq-google, cirq-ionq, cirq-aqt, cirq-pasqal and cirq-web. The consequence for you is a hard equality constraint across all six. A cirq-google left behind by an older release is not something pip quietly upgrades on your behalf, so an environment either resolves as a matched set or the install stops on the conflict. There is also a contrib extra, defined as cirq-core[contrib] pinned to the same version, so optional dependency sets cannot drift either.
Two pip commands point at two different documentation pages
Cirq asks for Python 3.11 or later and runs on Linux, macOS, Windows and Google Colab. Two install lines appear in the reference documentation section, and they are not interchangeable. The stable line pairs with the reference page for the current stable release. The nightly line installs a pre-release and pairs with the reference page that carries a version parameter, so mixing them gives you documentation for symbols your interpreter does not have.
pip install cirqpip install --upgrade cirq~=1.0.devThe newest release listed here is v1.7.0 from 2026-06-30, after v1.6.1 and v1.6.0 in 2025, and the repository is not archived, with its last push on 2026-11-01. Per platform setup steps are not spelled out in the README, which sends you to the Install section of the site instead. System level dependencies are tracked in apt-system-requirements.txt at the repository root.
Twenty repetitions is the whole quick start
The Hello Qubit snippet picks a qubit with cirq.GridQubit(0, 0), applies a square root of NOT, measures under the key 'm', and runs the circuit on a local simulator.
import cirq
# Pick a qubit.
qubit = cirq.GridQubit(0, 0)
# Create a circuit.
circuit = cirq.Circuit(
cirq.X(qubit)**0.5, # Square root of NOT.
cirq.measure(qubit, key='m') # Measurement.
)
print("Circuit:")
print(circuit)
# Simulate the circuit several times.
simulator = cirq.Simulator()
result = simulator.run(circuit, repetitions=20)
print("Results:")
print(result)What comes back is a circuit diagram and a bare count string.
Circuit:
(0, 0): ───X^0.5───M('m')───
Results:
m=11000111111011001000Twenty shots confirm that your install imports and runs. They do not separate a real effect from sampling noise, and nothing in the example computes an expectation value or an interval around those counts. A reader who treats that string as a result will read noise as signal. For more than a sanity check, the repository also ships examples such as examples/noisy_simulation_example.py and examples/direct_fidelity_estimation.py.
examples/ is a test suite that doubles as documentation
The examples directory ships runnable programs: bell_inequality.py, grover.py, qaoa.py, hhl.py, bernstein_vazirani.py, deutsch.py, hidden_shift_algorithm.py, phase_estimator.py, quantum_fourier_transform.py, magic_square.py, basic_arithmetic.py, bcs_mean_field.py, heatmaps.py and bb84.py. Sitting beside them are examples_test.py, conftest.py, and per file companions such as magic_square_test.py and direct_fidelity_estimation_test.py. That is the tell: these files are held to the same bar as the library rather than parked in a scratch folder. The layout mixes media and difficulty. direct_fidelity_estimation.py and direct_fidelity_estimation.ipynb sit side by side, an advanced/ subdirectory holds the heavier cases while the flat root holds short ones, and examples/README.md with examples/__init__.py make the folder an importable package. If you want to know which algorithms the project treats as canonical, this directory is the honest answer, and the Experiments page on the documentation site carries more of the same.
Coverage numbers are only honest from the repository root
The test configuration in pyproject.toml warns about its own working directory.
[tool.coverage.run]
include = [
# Omit files outside the current working directory.
# Note: this means coverage must be run from the cirq repo root.
# Failure to do so will result in false positives.
"./*",
]
omit = [
".venv/*",
"benchmarks/*"
]
patch = ["subprocess"]Run from anywhere else and coverage reports files it never loaded as uncovered, which is exactly what the comment calls false positives. benchmarks/ is omitted from the report entirely, so a gap inside the benchmark tree never surfaces in the numbers at all. The patch entry for subprocess extends coverage measurement to subprocesses. On Python 3.12 and later the core setting switches to sysmon to speed up pytest-cov through sys.monitoring, with a matching no-sysmon warning suppression for interpreters that lack it. Practical effect for a contributor: a coverage percentage from the wrong directory is worse than no number, because it looks like a measurement.
mypy refuses implicit reexports, so a top level import can fail to type check
Type checking is configured to be strict about what a module hands back to you.
[[tool.mypy.overrides]]
module = [
"cirq.*",
"cirq_aqt.*",
"cirq_google.*",
"cirq_ionq.*",
"cirq_pasqal.*",
"cirq_web.*"
]
no_implicit_reexport = trueA name that a Cirq submodule imports but does not declare itself is not re-exported, so inside the Cirq repository modules must re-export names explicitly for mypy to accept them. Two paths are excluded from checking outright, /setup.py and cirq-google/cirq_google/cloud/. exclude_gitignore is true, so the check follows the repository ignore rules, and warn_redundant_casts sits alongside warn_unused_ignores and the ignore-without-code error code setting, which together flag stale or code-less ignore comments in the checked code. Formatter settings push the same way: line length 100, a black profile shared with isort, and first party packages declared as cirq wildcard.
The integrations table sends hardware, error correction and chemistry elsewhere
Nine projects across seven rows carry work Cirq does not do itself, and the table maps an interest to a project.
| Your interests | Software to explore | |-------------------------------------------------|----------------------| | Quantum algorithms?<br>Fault-tolerant quantum computing (FTQC)? | [Qualtran] | | Large circuits and/or a lot of simulations? | [qsim] | | Circuits with thousands of qubits and millions of Clifford operations? | [Stim] | | Quantum error correction (QEC)? | [Stim] | | Chemistry and/or material science? | [OpenFermion]<br>[OpenFermion-FQE]<br>[OpenFermion-PySCF]<br>[OpenFermion-Psi4] | | Quantum machine learning (QML)? | [TensorFlow Quantum] | | Real experiments using Cirq? | [ReCirq] |
[Qualtran]: https://github.com/quantumlib/qualtran [qsim]: https://github.com/quantumlib/qsim [Stim]: https://github.com/quantumlib/stim [OpenFermion]: https://github.com/quantumlib/openfermion [OpenFermion-FQE]: https://github.com/quantumlib/OpenFermion-FQE [OpenFermion-PySCF]: https://github.com/quantumlib/OpenFermion-PySCF [OpenFermion-Psi4]: https://github.com/quantumlib/OpenFermion-Psi4 [TensorFlow Quantum]: https://github.com/tensorflow/quantum [ReCirq]: https://github.com/quantumlib/ReCirq
Qualtran takes quantum algorithms and fault tolerant computing, qsim takes large circuits and heavy simulation, Stim appears twice for thousands of qubits with millions of Clifford operations and for error correction, four OpenFermion projects take chemistry, TensorFlow Quantum takes machine learning, and ReCirq is the row for real experiments.
Python 3.11 through 3.14 is a formatter setting, not a support matrix
The formatter is configured with target-version covering py311, py312, py313 and py314 at line length 100, with string normalization skipped and generated protobuf files matching the pb2 pattern excluded from formatting. That list records the versions the code is written to run on, not the versions someone has tested it on. One platform statement exists in the README: Python 3.11 and later, on Linux, macOS, Windows and Colab. Contributor setup leans on one exploded list at dev_tools/requirements/deps/dev-tools.txt, and setup.py strips every entry containing a direct URL before handing the rest over, so requirements referenced by a direct URL never reach the dev set.
Editorial conclusion
Cirq suits researchers who already know which device or simulator they care about and want a Python API with device and noise modeling instead of a black box. Before you install, read the Install section of the online documentation for anything other than a default platform, and check that your interpreter matches the pinned metapackage. If you need error correction or chemistry tooling, budget for a second project on top. Teams choosing on the strength of published numbers should measure first, because the quick start here stops at twenty local shots.
Frequently asked questions
What is Cirq?
A Python framework for writing, manipulating and running quantum circuits on quantum computers and simulators, aimed at today's noisy intermediate scale machines. It covers flexible gate definitions, parameterized circuits with symbolic variables, circuit transformation and optimization, hardware device modeling, noise modeling, several built in simulators, and interoperability with NumPy and SciPy.
Is Cirq free to use?
The repository carries an Apache-2.0 LICENSE file at its root, and the project also points at a Zenodo DOI for citation. Learning materials come in three forms, with Jupyter notebook tutorials hosted on Colab that need no installation at all.
Is C++ used for quantum computing?
Cirq itself is Python. The repository root holds setup.py, pyproject.toml, conftest.py and a set of cirq prefixed packages, and the black formatter targets py311 through py314, with setuptools as the build backend. The README names qsim as the high performance simulation option but does not say what language it is written in.
Is Qiskit like Python?
Cirq's own primary language is Python, that interoperability is with NumPy and SciPy, and that specific tasks are delegated to sibling Google Quantum AI projects such as Stim, qsim and Qualtran.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/quantumlib-cirq)Star history chart for your README
[](https://hysenlabs.com/projects/quantumlib-cirq)Was this useful?