# TensorFlow Quantum: hybrid quantum-classical machine learning on Cirq and TensorFlow

> TensorFlow Quantum is Google's Apache-2.0 Python framework for building quantum circuits in Cirq and training them inside a TensorFlow graph. It is Linux-only, pinned to TensorFlow 2.19.1 and Cirq 1.5.0, and the last push to the repository was on 2026-09-01.

**tensorflow/quantum** — An open-source Python framework for hybrid quantum-classical machine learning.

- Repository: https://github.com/tensorflow/quantum
- Website: https://www.tensorflow.org/quantum
- Stars: 2,186 · Forks: 668
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/tensorflow-quantum

## The problem TFQ solves: gradients through a quantum circuit

Classical machine learning frameworks differentiate functions you wrote in Python. A quantum circuit is not that. It is a sequence of gates whose output is a measurement distribution, and the parameters you want to train sit inside gate rotations. TensorFlow Quantum exists to make those parameters trainable by the same optimizer that trains the classical part of the model.

The README frames the audience narrowly: "quantum algorithms and machine learning researchers" who need "fast simulation of many millions of moderately-sized circuits." That is a simulation-first positioning. TFQ is not a cloud client for real quantum hardware in the sense of being a hardware control stack; the README lists Cirq for circuit definitions and qsim for simulation, and describes the goal as modeling quantum data.

If you are a classical ML engineer curious about variational circuits, this is a reasonable entry point because the surrounding API is Keras. If you are a physicist who wants to run circuits on a device and read out histograms, Cirq alone is lighter and has fewer moving parts.

## How the Cirq, qsim and TensorFlow layers fit together

The architecture has three named layers. Cirq provides the circuit description. qsim provides the simulator. TensorFlow provides the training machinery, and Keras provides the high-level abstractions for quantum machine learning constructs.

The design decision that matters is where the quantum operations live. The README states that TFQ "implements operations as C++ TensorFlow Ops, making them 1st-class citizens in the TF compute graph." That is the difference between TFQ and a wrapper that shells out to a simulator per batch: the circuit execution is a node in the graph, so it participates in graph execution and in the automatic differentiation system.

Differentiation is handled by an "extensible system for automatic differentiation of quantum circuits," and the README lists several gradient methods, naming parameter shift and adjoint. Those two are not interchangeable in cost. Parameter shift evaluates the circuit twice per parameter, which grows with circuit width; adjoint methods trade that for memory and are typically used where the circuit structure allows it. The README does not state which method is selected by default, so treat the choice as something you configure and measure rather than assume.

The data flow a reader should hold in mind: a Cirq circuit plus a set of parameter values becomes a TensorFlow op inside the graph; the op returns measurement outcomes; a Keras layer or model consumes them; the optimizer updates the parameters, including the ones inside the circuit.

## Installing TensorFlow Quantum and running a first circuit

The README does not contain install commands. It says only: "Please see the installation instructions in the documentation," pointing to https://www.tensorflow.org/quantum/install. The PyPI package is named tensorflow-quantum, and the badge in the README links to https://pypi.org/project/tensorflow-quantum. Because the README gives no pip invocation, the only safe general statement is that installation happens through that documentation page and that the package is distributed on PyPI under that name.

What the README does state precisely is the compatibility matrix, and it is tight. TFQ is "built and tested on Linux" with Python 3.10 to 3.12, TensorFlow 2.19.1, TF-Keras 2.19.0, NumPy 2.0 and Cirq 1.5.0. Those are exact versions, not minimums. The repository reinforces this: requirements.txt is generated by pip-compile and there are separate lock files, requirements_lock_3_10.txt, requirements_lock_3_11.txt and requirements_lock_3_12.txt, one per supported Python minor version. The presence of three lock files tells you the maintainers treat the Python version as a build axis, and that a wheel built for one minor version is not interchangeable with another.

Because the README gives no command to run, the first concrete step is to open the PyPI project page linked from the badge, https://pypi.org/project/tensorflow-quantum, and confirm that a wheel exists for your interpreter before installing anything.

Once the environment matches, the README points to the notebook tutorials in docs/tutorials in the repository and to the guides at https://tensorflow.org/quantum/overview for a first working example. The README itself contains no runnable circuit, so the honest first step is to open one of those notebooks rather than to improvise an import.

The README includes a BibTeX citation entry for the 2021 TFQ paper (arXiv:2003.02989) and asks that you include the TFQ version you used when citing it in published work. It is not a runnable command.

## Where TensorFlow Quantum is the wrong tool

The platform restriction is the first hard boundary. The README says TFQ is built and tested on Linux, and it does not claim Windows or macOS support. If your team develops on laptops running macOS, you are looking at containers or remote Linux hosts for every experiment. That is a real cost that does not appear in the feature list.

The version pinning is the second boundary. TensorFlow 2.19.1, TF-Keras 2.19.0, NumPy 2.0 and Cirq 1.5.0 are named as the tested combination. If your classical stack is on a different TensorFlow minor version, you cannot simply install TFQ alongside it and expect the graph ops to line up. The release history shows the cadence: v0.7.3 in May 2024, v0.7.5 in December 2025, v0.7.6 in February 2026. Gaps of more than a year between releases mean a dependency bump in TensorFlow can leave you waiting.

The third case is scale. The README describes the target as millions of moderately-sized circuits. That wording is a warning about circuit width. Simulation cost grows with the number of qubits, and the adjoint and parameter shift methods both add overhead on top. If your circuit is wide, no amount of TensorFlow graph optimization makes up for the simulator's memory. TFQ is the wrong tool when the experiment needs a real device rather than a simulation, and it is also the wrong tool when the circuit is small enough that a plain Cirq script and a hand-written loop would finish faster than the setup work.

Finally, the README carries a disclaimer: "This is not an officially supported Google product," and the project is not eligible for the Google Open Source Software Vulnerability Rewards Program. That is a support boundary, not a defect, but it belongs in the adoption decision.

## TensorFlow Quantum compared with Cirq and PennyLane

Cirq is the closest comparison because TFQ is built on it. Cirq gives you circuits, simulators and hardware interfaces, and it is usable on its own. The difference is the training loop: with Cirq you write the parameter update yourself, and you compute gradients with whatever method you implement. TFQ takes those same circuits and makes their execution a TensorFlow op, so the optimizer, the batching and the Keras model all apply to the circuit parameters. If you never intend to train anything, Cirq is the smaller dependency and the shorter path.

PennyLane takes a different approach to the same problem. It is built around automatic differentiation of quantum circuits with interfaces to several classical frameworks, rather than being an extension of one. The practical consequence is that a PennyLane workflow is not tied to TensorFlow's version cadence, and the choice of classical backend is a configuration rather than an architectural commitment. The trade-off runs the other way too: TFQ's ops are C++ TensorFlow ops inside the graph, which the README presents as the source of its performance and scalability, and that integration is not something a framework-agnostic layer reproduces by wrapping a simulator.

Pick TFQ when the classical model really is a TensorFlow model and the quantum circuit is a layer in it. Pick PennyLane when you want to move the same circuit between classical backends. Pick Cirq when there is no training loop.

## Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-01, which is recent relative to the 2026-02-25 release of v0.7.6. The release tags, though, are sparse: v0.7.3 in May 2024, v0.7.5 in December 2025, v0.7.6 in February 2026. Commits and releases are not the same signal, and the gap between v0.7.3 and v0.7.5 is the one to weigh if your plan depends on regular versioned drops.

Upgrade cost is dominated by the pinned matrix. Moving to a newer TensorFlow means waiting for a TFQ release that lists it as tested, and moving to a newer Python minor version means a new lock file and a new wheel. The repository layout supports that reading: requirements.in feeds pip-compile through ./scripts/generate_requirements.sh, producing requirements.txt and the per-version lock files. Upgrades are a build-matrix event, not a version bump in a config file.

Licensing is Apache-2.0, per the LICENSE file and the badge. That is a permissive licence with an explicit patent grant, which is generally the least friction for commercial use, but the README's disclaimer that this is not an officially supported Google product is separate from the licence and should be read on its own. Nothing here is legal advice; if the patent grant or the notice requirements matter to your organisation, have counsel read the LICENSE file.

For help, the README directs bugs and feature requests to the GitHub issue tracker and general discussion to the Stack Overflow tag tensorflow-quantum. There is also a contact address, quantum-oss-maintainers@google.com, for questions the README does not cover.

## Conclusion

Adopt TensorFlow Quantum if you already write Cirq circuits and want gradients from them inside a Keras training loop, and if your machines run Linux with Python 3.10 to 3.12. Do not adopt it if you need Windows or macOS support, or if you want a framework that tracks the newest Cirq and TensorFlow releases, because the README pins TensorFlow 2.19.1, TF-Keras 2.19.0, NumPy 2.0 and Cirq 1.5.0. Before committing, verify that your exact Python and TensorFlow combination has a published wheel on PyPI, and read the installation page rather than the README, which gives no commands.

## FAQ

### What is TensorFlow Quantum?

It is an open-source Python framework for hybrid quantum-classical machine learning, licensed under Apache-2.0. It combines Cirq for circuit definitions, qsim for simulation, and TensorFlow and Keras for the training machinery.

### How do I install TensorFlow Quantum?

The README does not give install commands; it points to the installation instructions at tensorflow.org/quantum/install, and the package is published on PyPI as tensorflow-quantum. The README states it is built and tested on Linux with Python 3.10 to 3.12, TensorFlow 2.19.1, TF-Keras 2.19.0, NumPy 2.0 and Cirq 1.5.0.

### Does TensorFlow Quantum run on Windows or macOS?

The README says only that TensorFlow Quantum is built and tested on Linux, and it names no other supported platform. Windows and macOS are not mentioned as supported configurations.

### Which gradient methods does TensorFlow Quantum provide for quantum circuits?

The README lists an extensible system for automatic differentiation of quantum circuits and says it offers many methods for computing gradients, naming parameter shift and adjoint methods. It does not state which method is used by default.

## Sources

- [License: Apache-2.0](https://github.com/tensorflow/quantum/blob/master/LICENSE)
- [Project website](https://www.tensorflow.org/quantum)
- [README](https://github.com/tensorflow/quantum/blob/master/README.md)
- [Releases](https://github.com/tensorflow/quantum/releases)
- [tensorflow/quantum on GitHub](https://github.com/tensorflow/quantum)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tensorflow-quantum