TensorFlow GNN: a 2.12 floor in the README, a 2.17 floor in the metadata
TensorFlow GNN is a library to build Graph Neural Networks on the TensorFlow platform.
At a glance
- What is it?
- TensorFlow GNN ships a GraphTensor type, a Beam-backed graph sampler, and a training runner, and its own files disagree about the TensorFlow floor, the Python floor, and the platforms it supports. Installing from source runs Bazel before setuptools.
- Who is it for?
- This is a Google port of an internal graph library, and it is built for one operating system and one Keras generation even though the packaging metadata claims three of each. Read it as a Linux, Keras v2 library with a Bazel-backed source build, and set TF_USE_LEGACY_KERAS=1 before anything else or the import path you have been reading about will not be the one you get.
- 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 received new commits within the last day.
- 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.
Star history
- tensorflow/gnn1,551 ★ · +11
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| tensorflow/gnn | 1.5k | 1.6k |
11 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The README promises TensorFlow 2.12, the metadata demands 2.17
The install section states the key platform requirements as of release 1.0 and lists TensorFlow 2.12 or higher, then adds a parenthetical that future releases will raise the required TF version. The package metadata has already done that. The dependency list in pyproject.toml pins tensorflow>=2.17.0, <3 alongside tf-keras>=2.17.0, <3, and declares requires-python as >=3.10, <4. A reader who trusts the prose and installs on TensorFlow 2.12 satisfies the README and fails the resolver. The published command is one line.
pip install tensorflow-gnnThe same metadata pulls ml-collections, networkx, pyarrow, and tensorboard as hard requirements, so pip resolves a graph library, an arrow columnar stack, and a logging stack on your behalf whether you asked for them or not. It also marks the version as dynamic, meaning the version string is produced at build time rather than written into the file a reader would check.
TF_USE_LEGACY_KERAS=1 is the step metadata cannot express
The platform requirements say TF-GNN does not work with the new multi-backend Keras v3, and that users of TF2.16 and later must also pip install tf-keras and set TF_USE_LEGACY_KERAS=1. The install half of that instruction is already redundant, because tf-keras is a declared dependency at the same 2.17 floor as TensorFlow itself. The environment variable is the part that is not: a flag read at import time cannot be encoded as a version constraint, so every environment running this library carries the same manual step that no resolver will perform for it. Two more requirements hide in the same list. Apache Beam is needed for distributed graph sampling, and for tests or scripts that require tensorflow.lite the reader is told to install ai-edge-litert, a package absent from the dependency list because nothing in the library imports it at runtime. That split is the general shape of the requirements here: anything on the training path is a declared dependency, and anything needed only by a test or a notebook is a sentence in the install section.
The Dockerfile runs Python 3.9 against a package that requires 3.10
The container recipe in the repository root starts from python:3.9-slim, which is below the requires-python floor of 3.10 the same repository declares. It also pins an older release than the newest tag, installing tensorflow-gnn==1.0.0 while v1.0.3 is the current one, upgrades pip first, and adds httplib2, notebook, and ogb so that the image can open the example notebooks rather than just import the library. It fixes the timezone to America/New_York with a comment about tzdata asking questions. Two commands in its comments show the intended loop.
docker build . -t tfgnn:latestdocker run -it tfgnn:latestThe platform story conflicts in the other direction. The README says the library is developed and tested on Linux, and that running on other platforms supported by TensorFlow may be possible, while the classifiers in pyproject.toml claim MacOS X, POSIX Linux, and Microsoft Windows. Both statements ship inside the same package.
pip install runs Bazel before setuptools gets a chance
setup.py replaces the distutils build command with one that invokes a bazel build before any sub-command runs, in order to generate protocol buffer files and C++ extension modules. Its own docstring is explicit that the override is reached from three entry points, pip install ., python setup.py install, and the bdist_wheel path, so there is no route around it that skips the toolchain. The overridden command also forces C extension compilation to report true, so the native build is not optional even on a wheel. That is why the repository root carries BUILD, WORKSPACE, a .bazelversion file, and a MANIFEST.in: a source install of a Python package that first compiles native extensions and generates protocol buffers. The root also holds package/, ci/, testdata/, and the tensorflow_gnn/ package itself, and the install section sends anyone building from source to a separate Developer Guide rather than inlining the steps. The Colab notebooks exist precisely because none of that machinery is needed to read the tutorials.
Every quickstart link addresses a branch called master
The three Colab notebooks that make up the quickstart are linked through paths of the form blob/master/examples/notebooks/, ending in intro_mutag_example.ipynb, ogbn_mag_e2e.ipynb, and graph_network_shortest_path.ipynb. The repository's default branch is main, so the tutorials are addressed through a branch name that is not the one a clone lands on. The file carries a second class of fragile path: nearly every documentation reference is relative, pointing into tensorflow_gnn/docs/guide/, and the metadata holds a standing note that those relative links from README.md do not work on PyPI, tracked under an internal bug reference. Read the page on GitHub and the documentation links resolve; read it on the package index and they do not. Everything else routes through a single portal, a documentation overview page that links the colabs, the user guides, and the API docs in one place, which is a second reason to work from the repository rather than from the installed package. The quickstart also frames the notebooks as the supported first experience, promising the demos in a browser with no installation required.
The required citation ends on a dangling and
The citation section asks that any paper referencing the library cite the TF-GNN paper, given as an arXiv link, and the BibTeX entry that follows is unfinished. It opens as an article entry keyed tfgnn, then runs through more than twenty authors, from Oleksandr Ferludin and Arno Eigenwillig through Martin Blais, Vahab Mirrokni, John Palowitch, Mihir Paradkar, and Jennifer She, where it stops on the word and. The author list has no closing brace and the year never appears. Anyone lifting that block into a bibliography has to reconstruct the tail themselves. The paper it points to is the same one the summary already links twice, once by number and once by title, and the summary also points at a February 2024 blog post announcing the library to the TensorFlow blog.
Two years of commits, one release since May 2024
The tag history is three entries across four months: v1.0.2 on 2024-02-06, v1.0.3rc0 on 2024-04-24, and v1.0.3 on 2024-05-13. The last commit to main landed on 2026-09-29. The released artifact a pip install resolves has therefore not moved in more than two years while the repository has, which matters for a library whose Python and Keras requirements both drifted upward after that tag. The extras tell the same story from the other side: the vizier extra pins google-vizier>=0.0.13 and excludes version 0.1.23 outright, and Vizier appears nowhere in the installation or usage sections. The examples tree, meanwhile, is organized as notebooks, sampler, schemas, and tutorials, with testdata/ and ci/ sitting beside it. The metadata around all of this describes the project as Google LLC, classifies it as Production/Stable for developers and science or research audiences, and routes contact to a googlegroups.com address. An rc tag still sits in the release list alongside the stable one, which is a normal practice and also the only signal on the page about how releases are cut.
One database becomes a stream of subgraphs, and Beam does the work
The summary is four bullets, and the second is the one that shapes everything else. It describes a graph sampler whose job is to convert a huge database into a stream of reasonably-sized subgraphs for training and inference, which is what makes neighborhood aggregation over a full graph impractical otherwise. Distributed sampling is where Apache Beam enters, which is why Beam sits in the dependency list with a floor of 2.57. The first bullet is the data model: a GraphTensor type representing graphs with a heterogeneous schema, meaning several types of nodes and edges in one graph rather than a single node type, with its own guide pages for the tensor and for the schema. The two tutorials that use the type show both halves of that idea: MUTAG is a plain molecular graph with one kind of node, while OGBN-MAG is heterogeneous and is trained on sampled subgraphs end to end. The remaining two bullets cover a set of ready-to-use models and Keras layers for your own modeling, and a high-level API for training orchestration, each behind its own guide page.
Editorial conclusion
This is a Google port of an internal graph library, and it is built for one operating system and one Keras generation even though the packaging metadata claims three of each. Read it as a Linux, Keras v2 library with a Bazel-backed source build, and set TF_USE_LEGACY_KERAS=1 before anything else or the import path you have been reading about will not be the one you get. Before following the quickstart, note that its notebook links address a branch named master while the default branch is main. And before depending on it, check whether the fix you need shipped after v1.0.3, the only release since May 2024, given that commits are still landing.
Frequently asked questions
What is a GNN used for in TensorFlow GNN?
The quickstart demonstrates three shapes of work: molecular graph classification on the MUTAG dataset, training on heterogeneous sampled subgraphs for the OGBN-MAG node property benchmark, and predicting the edges of a shortest path with an Encoder, Process, Decoder architecture. The library describes itself as a port of a Google-internal library used on homogeneous and heterogeneous graphs.
Is GNN better than CNN?
The repository offers no comparison and no benchmark table, so it cannot answer that. What it states is narrower: that TF-GNN is an open source port of a Google-internal library used alongside other scalable graph mining tools, on graphs that may carry several node and edge types.
Which Keras version does TensorFlow GNN need?
Keras v2. The library does not work with the new multi-backend Keras v3, and users of TF2.16 and later must pip install tf-keras and set TF_USE_LEGACY_KERAS=1. tf-keras is already a declared dependency at the 2.17 floor.
What does installing TensorFlow GNN from source require?
Bazel. setup.py overrides the distutils build command so that a bazel build runs first, generating protocol buffer files and C++ extension modules, and the override is reached from pip install ., from python setup.py install, and from bdist_wheel. The root carries BUILD, WORKSPACE, and .bazelversion.
Which platforms does TensorFlow GNN support?
The README says it is developed and tested on Linux, and that other platforms supported by TensorFlow may be possible. The package metadata is broader, with classifiers for MacOS X, POSIX Linux, and Microsoft Windows.
What extras does TensorFlow GNN declare?
A vizier extra, pinning google-vizier>=0.0.13 and excluding version 0.1.23. Nothing about Vizier appears in the installation or usage sections.
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/tensorflow-gnn)Star history chart for your README
[](https://hysenlabs.com/projects/tensorflow-gnn)Was this useful?