Library / SDK
tensorflow/quantum avatar
tensorflow/quantum

TensorFlow Quantum: installation, compatibility and support

An open-source Python framework for hybrid quantum-classical machine learning.

2,204 stars675 forksPythonApache-2.0

At a glance

What is it?
tensorflow/quantum is an Apache-licensed Python framework for hybrid quantum-classical machine learning, layering quantum circuits written in Cirq and simulated with qsim onto TensorFlow and Keras, with the operations implemented as native TensorFlow ops in C++. What the readme establishes is a narrow compatibility matrix on one operating system, no install command on the page at all, and a disclaimer that rules the project out of Google's bug bounty programme.
Who is it for?
Use TensorFlow Quantum if you are already inside TensorFlow and need differentiable quantum circuits as graph operations, because the C++ op implementation is the reason to choose it over a pure Python circuit library. Three things to accept before you start.
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 November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • tensorflow/quantum2,204 ★ · +22
Star history
Repository2026-09-112026-11-15
tensorflow/quantum2.2k2.2k

22 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One operating system, five exact pins, and no install command

The installation section is four sentences long and contains no command. It asks you to see the installation instructions in the documentation, then gives the compatibility matrix as the only hard information on the page.

That matrix is narrow in a way worth reading closely. TensorFlow Quantum is built and tested on Linux, and Linux is the only operating system named. The supported Python versions are given as a range, 3.10 to 3.12. Everything else is a single exact version: TensorFlow 2.19.1, TF-Keras 2.19.0, NumPy 2.0 and Cirq 1.5.0.

The mixing of a range for the interpreter and pins for every library is a deliberate choice rather than an omission. It says the framework tracks specific library versions and rebuilds against them, and that the interpreter can float within a range. For a project whose operations are compiled C++ and linked against TensorFlow's ABI, that is the correct way to publish compatibility: a reader knows that a different TensorFlow minor is not a supported configuration rather than an untested one.

For anyone on macOS or Windows, the page offers no guidance at all, which leaves the practical question of whether a build works to be discovered rather than documented.

Citing the TensorFlow Quantum framework

The README asks researchers who use TensorFlow Quantum to cite its framework paper and state the version they used. It includes a complete BibTeX entry with the author list, DOI and arXiv link. When reporting a result, record the framework version and relevant simulation and differentiation settings so others can reproduce the experiment.

Not an officially supported product, and not eligible for the bounty

The disclaimer is three sentences and it is the most consequential thing on the page.

First: this is not an officially supported Google product. Second: the project is not eligible for the Google Open Source Software Rewards programme for open source security vulnerabilities. Third: the copyright is dated 2020.

For a security researcher, the second sentence removes any financial reason to report a vulnerability here, and it means disclosure depends entirely on good faith. For an adopter, the first sentence means the compatibility matrix is a statement of what was tested rather than a support commitment, and the third sentence tells you the licence header has not been revisited in six years.

The support paths the page does give are all community ones. Bugs and feature requests go to the GitHub issue tracker. General questions have a Stack Overflow tag. Everything else goes to a maintainers mailbox at the company domain.

None of that makes the project unsuitable. It makes the framework a research tool maintained by people who work on it rather than a product with a service level behind it, and the difference matters if you are about to build a pipeline on it.

Three lock files, one per Python minor, every package hash-pinned

The dependency management in this repository is more rigorous than the readme's tone suggests, and the tree is where you find it.

There is an input file for the requirements and then four generated ones. Three of the generated files are locks named for the Python versions in the support matrix, one each for 3.10, 3.11 and 3.12, which is how you support a range of interpreters with exact dependency sets. The fourth is the file that most people will read first, and its header says it was autogenerated by a compile step with Python 3.10 and names the script that generates it.

What the generated file contains is the part that surprises people. Every package is pinned to an exact version and carries one or more SHA-256 hashes, so an install verifies the artefact rather than trusting the index. Under each pin is a comment naming what required the package, generated from the dependency graph.

Those comments also reveal that the resolved set is much larger than the four libraries in the compatibility matrix. Cirq arrives as a package called cirq-core with its own transitive set, which pulls in a schema validator, a references library and a units library. The documentation toolchain appears in the same graph, and with it static analysis tooling: a linter and its own dependency graph are resolved into the same file.

So the honest summary is that the runtime you install is small and the environment you install it into is not, and the hash pinning is what makes the difference tolerable.

The operations are C++, and that is why a Bazel workspace is in the tree

One bullet in the feature list explains the repository layout better than the rest of the readme does. The operations are implemented as native TensorFlow operations in C++, which the page says makes them first-class citizens in the compute graph.

That single decision cascades. A native operation needs a kernel compiled against TensorFlow, which needs a build system beyond setuptools, and the root of the repository accordingly holds a build definition, a workspace definition and a pinned build tool version file, alongside a shell script that configures the build and a third-party dependencies directory. If you have seen a TensorFlow project with those files at its root, this is why.

The consequence for a Python user is that this is not a pure Python package. There is a compilation step somewhere between the source you clone and the operations you call, and the readme does not mention it, because the installation instructions it points you to are the place where that is documented.

The rest of the tooling configuration is consistent with a C++ and Python hybrid: a formatting configuration for C++, a style file for the Python formatter, a linter configuration, a Markdown lint configuration and a YAML lint configuration. Six files, five languages of tooling, which is normal for a project of this kind and unusual for a Python library that describes itself with a Python badge.

Gradients come from parameter shift and from the adjoint method

The differentiation story is the part of this framework that is genuinely different from classical machine learning, and the feature list names two techniques.

The first is a parameter shift method for computing gradients. In a variational quantum algorithm the parameters enter a circuit as rotations, so a gradient can be estimated by evaluating the same circuit at shifted parameter values rather than by differentiating through it. The second is the adjoint method, which computes the gradient of a circuit's expectation value in work proportional to the circuit rather than to the number of parameters.

Neither technique is an implementation detail, and that is why the framework exists at all. A quantum circuit is not differentiable in the way a neural network is, so a framework that claims automatic differentiation has to make a choice about how gradients are obtained, and it advertises an extensible system for doing so plus several concrete methods.

The pairing with TensorFlow matters here. If the circuit is a native operation in the graph, a gradient computed by either method flows through the same machinery as a gradient through any other operation, which means an optimiser from Keras and a quantum circuit can be composed without either one knowing about the other. That composition is the argument for the C++ implementation.

Cirq writes the circuits, qsim simulates them, Keras abstracts them

Three dependencies have clearly separated jobs, and understanding which is which tells you what you write yourself and what you get.

Cirq is where quantum circuit definitions are written. It is a separate project with its own repository, and TFQ integrates with it rather than replacing it. So the object you build is a Cirq circuit, and learning TFQ partly means learning Cirq.

qsim is where circuits are run. It is the simulation engine, also a separate project, and the choice of it as the default says something about the intended scale: the page frames the framework as being for questions that can only be answered by fast simulation of many millions of moderately sized circuits. That is a simulation statement, not a hardware statement.

Keras provides the high-level abstractions for quantum machine learning constructs, which is the layer where a quantum layer becomes something you stack, train and regularise like any other layer. It is also why the compatibility matrix pins a separate package for the Keras implementation rather than relying on the one TensorFlow ships, which is a detail that matters for anyone who has hit a Keras version conflict inside TensorFlow.

Read the three together and the framework's scope is clear: classical training machinery wrapped around simulated circuits, differentiable, at scale.

The documentation is on a web site, and the repository keeps notebooks

The readme's quick start section is a list of links and a sentence. Guides and tutorials are on the project page. Documentation is on the project page. The examples are in the repository, as notebook tutorials.

So of the three things a newcomer needs, two live outside the repository and one lives inside it. That is an unusual division for a project whose licence is permissive and whose source is public, and it has a practical consequence: a versioned documentation snapshot does not exist for any release, and an offline reader gets only the notebooks.

The notebooks themselves are the best argument for keeping them. A notebook is executable documentation, it shows the shape of an experiment rather than a list of flags, and for a research framework that is worth more than prose. A directory of tutorials covering the main areas sits under the documentation folder and is referenced from the readme.

What the readme does contribute is the two pieces that change with releases: the compatibility matrix and the citation requirement. Those are the lines to re-check when you upgrade, and both are the kind of thing that goes stale silently, since neither fails loudly when it is out of date.

The release history supports reading them carefully: a patch in December 2025, another in February 2026, and before those a gap back to May 2024. The last push to the master branch is 2026-09-01, so development continues between releases.

Editorial conclusion

Use TensorFlow Quantum if you are already inside TensorFlow and need differentiable quantum circuits as graph operations, because the C++ op implementation is the reason to choose it over a pure Python circuit library. Three things to accept before you start. That it is a Linux project, since the compatibility statement names one operating system alongside exact versions of TensorFlow, TF-Keras, NumPy and Cirq, so a macOS or Windows workflow is not covered by anything the page claims. That support is community support: bugs go to an issue tracker, questions to a Stack Overflow tag and a maintainers mailbox, and the project states plainly that it is not an officially supported Google product and is not eligible for the security vulnerability rewards programme. And that the reference documentation lives on the web rather than in the repository, which keeps only notebook tutorials in the tree. The good news is the dependency pinning, which is thorough to the point of hash-locking every package for three Python versions.

Frequently asked questions

What is TensorFlow Quantum?

It is an Apache-2.0 licensed Python framework for hybrid quantum-classical machine learning focused on modelling quantum data. It interleaves quantum algorithms with TensorFlow's machine learning tools, writes circuit definitions with Cirq, runs simulations with qsim, uses Keras for high-level abstractions, and implements its operations as native C++ TensorFlow ops.

Which platforms does TensorFlow Quantum support?

Linux. The compatibility statement says 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. No other operating system is named, and the readme gives no guidance for macOS or Windows.

How do I install TensorFlow Quantum?

The README links to the official installation guide at https://www.tensorflow.org/quantum/install, which provides detailed source-build steps. Check the guide for current requirements and platform support before installing.

How does TensorFlow Quantum compute gradients?

It provides an extensible system for automatic differentiation of quantum circuits and offers several methods for computing gradients, naming parameter shift and adjoint methods among them. Because the operations are implemented as C++ TensorFlow ops, those gradients flow through the same graph machinery as any other operation, which is what lets a Keras optimiser and a quantum circuit be composed.

Is TensorFlow Quantum officially supported by Google?

No. Its disclaimer says it is not an officially supported Google product and that it is not eligible for the Google Open Source Software Rewards programme for open source security vulnerabilities, with copyright dated 2020 Google. Support is community based: bugs go to the GitHub issue tracker, general questions to a Stack Overflow tag, and everything else to a maintainers mailbox.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. tensorflow/quantum on GitHub
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.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tensorflow-quantum.svg)](https://hysenlabs.com/projects/tensorflow-quantum)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tensorflow-quantum.svg)](https://hysenlabs.com/projects/tensorflow-quantum)

Was this useful?