TensorFlow Quantum: Cirq Circuits Inside a TensorFlow Graph
An open-source Python framework for hybrid quantum-classical machine learning.
At a glance
- What is it?
- TFQ is a Python framework that turns Cirq circuit definitions into TensorFlow ops so quantum and classical layers can be trained together. The design is coherent, but the install matrix is narrow and the project is explicitly not an officially supported Google product.
- Who is it for?
- Adopt TFQ if you are already writing circuits in Cirq and want to train a classical model on top of circuit outputs without leaving the TensorFlow graph, and if you can pin Linux, Python 3.10 to 3.12, TensorFlow 2.19.1, TF-Keras 2.19.0, NumPy 2.0 and Cirq 1.5.0. Do not adopt it for hardware execution, for production services, or for a stack that cannot hold that pin.
- 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 14 days 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 September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap TFQ fills between circuit libraries and training loops
A circuit library such as Cirq lets you describe a quantum program and simulate it. A classical framework such as TensorFlow lets you define a differentiable model and train it. The awkward part has always been the seam between the two: getting measurement statistics out of a circuit, feeding them into a classical layer, and propagating gradients back into circuit parameters. TFQ targets that seam. The README describes it as a framework "focused on modeling quantum data," and the stated audience is quantum algorithms and machine learning researchers who need fast simulation of large batches of circuits. The README also notes the project has been used in QML research connected to Google's quantum computing offerings. The claim of being "instrumental" in prior research is the README's own framing, not an independent measurement. What matters for an adoption decision is narrower: if your circuits are written in Cirq and your model is written in Keras, TFQ is the piece that makes them one trainable object.
How a Cirq circuit becomes a TensorFlow op
The mechanism the README describes is that TFQ implements its operations as C++ TensorFlow Ops, which makes them first-class citizens in the TensorFlow compute graph. That is the structural decision the rest of the framework follows from. Circuits are authored in Cirq, simulation is delegated to qsim, and Keras supplies the high-level abstractions for the quantum machine learning constructs. Because the quantum operations live in the graph rather than beside it, the framework can offer what the README calls an extensible system for automatic differentiation of quantum circuits, with multiple gradient methods including parameter shift and adjoint. The practical consequence is that a hybrid model is not two programs exchanging arrays. It is one graph in which some nodes happen to evaluate circuits. The cost of that design is that the C++ op layer is the load-bearing part, and the compatibility table below is really a statement about which TensorFlow builds those ops were compiled against.
Installation is a pinned matrix, not a pip install
The README does not give a pip command. It points to the installation page in the documentation, which is a signal worth reading literally: there is no one-line install that will work on an arbitrary machine. What the README does give is a compatibility statement. At the time of writing, TensorFlow Quantum 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. Every entry in that list is a pin. NumPy 2.0 in particular is not a range, and the TensorFlow and Keras versions are exact. If your environment already carries a different TensorFlow build, the C++ ops were not compiled for it. The README's Quick Start section contains no code either; it routes to the guides and tutorials on tensorflow.org and to the notebook tutorials under docs/tutorials in the repository. For an evaluation, the notebooks are the fastest way to see a working configuration, because they encode a known-good environment rather than the one you happen to have.
The platform constraint is the real adoption cost
Linux only is stated plainly in the README, not buried. That single line rules out native Windows and macOS workflows for anyone who wants the tested path. It does not mean the framework cannot be used from those machines, but the README does not describe a supported route, so treating it as unsupported is the honest reading. The second constraint is the version pinning. A team whose other services depend on a newer TensorFlow, or on a NumPy release outside 2.0, faces a choice between isolating TFQ in its own environment and holding the rest of the stack back. The third constraint is quieter: the README's disclaimer states this is not an officially supported Google product and that it is not eligible for the Google Open Source Software Vulnerability Rewards Program. That is a maintenance signal, not a quality judgement. It means the project does not come with the support guarantees that the Google name might imply, and a team that needs a vendor relationship should look elsewhere. The release history shows steady but not high-frequency activity, with v0.7.6 in February 2026 following v0.7.5 in December 2025 and a longer gap back to v0.7.3 in May 2024.
When Cirq alone, or Qiskit, is the better tool
The clearest alternative is Cirq by itself, which TFQ already depends on for circuit definition. If your goal is to construct circuits, simulate them, and inspect results, Cirq does that without TensorFlow, without the C++ op layer, and without the version matrix. You lose automatic differentiation of circuit parameters through a training loop, which is the entire reason TFQ exists, and you gain a much smaller dependency surface. The second alternative is Qiskit, which is a different ecosystem rather than a drop-in. Qiskit's circuit model and its transpilation and hardware backends are its centre of gravity; TFQ's centre of gravity is the TensorFlow graph. Choosing between them is mostly a question of where your model already lives. A team with an existing Keras pipeline and Cirq circuits gets a short path from TFQ. A team whose work is circuit-level, or whose target is real hardware, gets little from the hybrid training machinery and pays the install cost for nothing. TFQ is also the wrong tool when the research question is about hardware behaviour rather than model training, because the framework's stated focus is simulation.
Licence and the cost of staying current
TFQ is Apache-2.0, which permits commercial and closed-source use and includes an express patent grant. That is a permissive licence and it is the least of the concerns here. The maintenance cost is the version matrix. Every upgrade of TensorFlow, Keras, NumPy or Cirq becomes a coordinated event rather than an independent one, because the C++ ops are built against specific versions. The README's compatibility list is the document to check before any upgrade, and it is the reason a floating dependency policy will break a TFQ environment. The practical pattern is to isolate TFQ in its own environment and treat the pins as part of the application, not as incidental. This is not legal advice; the Apache-2.0 text in the repository's LICENSE file governs, and the citation request in the README is a request rather than a licence term.
Editorial conclusion
Adopt TFQ if you are already writing circuits in Cirq and want to train a classical model on top of circuit outputs without leaving the TensorFlow graph, and if you can pin Linux, Python 3.10 to 3.12, TensorFlow 2.19.1, TF-Keras 2.19.0, NumPy 2.0 and Cirq 1.5.0. Do not adopt it for hardware execution, for production services, or for a stack that cannot hold that pin. Before committing, verify that a current TensorFlow and NumPy pair installs cleanly on your platform, and check whether the parameter shift or adjoint gradient path covers the observables and circuit structure you intend to differentiate.
Community notes