PyG's pyproject carries no torch, and its version runs ahead of its release tags

No torch entry anywhere in the dependency list

Start with the dependency list, because it answers most of the support questions people ask about this library. torch-geometric 2.9.0 declares aiohttp, fsspec, jinja2, numpy, psutil>=5.8.0, pyparsing, requests, tqdm and xxhash. There is no torch entry in that list. PyG is built on PyTorch, but the PyTorch build is yours to install: the CPU wheel or the CUDA build, and the version, are all decided outside this package.

That is the point of a tensor-centric API whose design principles stay close to vanilla PyTorch, and it carries a direct cost. The surrounding features, torch.compile support, multi GPU support, DataPipe support, sit on your PyTorch build rather than on any PyG pin. The library cannot hand you a working GPU or compile path by itself: if the torch build you installed lacks a feature, no PyG version supplies it. Install the PyTorch build you need first, then install PyG into that same environment.

pyproject says 2.9.0, the newest tag says 2.8.0

Version numbers in this repository deserve a second look, because the file and the release tags disagree. pyproject declares version="2.9.0". The newest listed release is 2.8.1, dated 2026-10-06, preceded by 2.8.0 on 2026-06-05 and 2.7.0 on 2025-10-14. The most recent push to the default branch, master, is dated 2026-10-21, and the repository is not archived.

The gap between 2.9.0 in the file and 2.8.1 in the release list is the practical issue. Anything taken from the default branch is a version ahead of what has been published, so an install from the master tree is not a released artefact and its behaviour can change without any tag appearing. The spacing between tags matters too, since 2.7.0 to 2.8.0 covers roughly eight months. If you need a fixed point, pin to a release tag rather than tracking the branch.

Python 3.10 is a floor, and there is no ceiling

The Python support statement is a floor rather than a window. requires-python is >=3.10 with no upper bound, and the classifier list runs 3.10, 3.11, 3.12, 3.13 and 3.14, alongside Programming Language :: Python :: 3 :: Only. The build backend is flit_core, required at >=3.12,<4, the distribution is named torch-geometric while the import path is torch_geometric, and the licence is MIT with the licence file shipped alongside.

Two consequences follow. On anything older than 3.10 the install is refused outright rather than degraded, so a 3.9 environment inherited from older research code has to be upgraded before PyG is even a candidate. On the other side, the absent ceiling means a newly released interpreter is not blocked by metadata, so whether PyG actually works there comes down to the PyTorch wheel you can obtain, not to what PyG asserts. The classifier list advertises 3.14 support; the torch build remains your problem to solve.

edge_index is the one convention, and you build it

The API is a single convention repeated everywhere: a node feature matrix and an edge_index connectivity matrix, both plain tensors, handed to forward. The training loop from the quick tour shows it end to end:

import torch.nn.functional as F

data = dataset[0]
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)

for epoch in range(200):
    pred = model(data.x, data.edge_index)
    loss = F.cross_entropy(pred[data.train_mask], data.y[data.train_mask])

    # Backpropagation
    optimizer.zero_grad()
    loss.backward()
    optimizer.step()

No graph object appears in that loop. Whichever edges you have, from a dataset or from your own construction, they arrive as that one tensor, and the training mask and labels come from the same data object. Transforms are provided for arbitrary graphs and for 3D meshes and point clouds.

MessagePassing is the seam, and it costs Python code

Custom architectures are written against MessagePassing, with the edge convolutional layer from Wang et al. as the worked example. The constructor picks the aggregation rule and builds the MLP over concatenated node features:

class EdgeConv(MessagePassing):
    def __init__(self, in_channels, out_channels):
        super().__init__(aggr="max")  # "Max" aggregation.

What that buys is a place to put a message function and an aggregation, which is the extension point the highlights mean when they describe flexibility for your own research. The repository layout backs it up: examples/ contains cpp, compile, contrib, distributed and explain subdirectories next to flat files such as dgcnn_classification.py, dgcnn_segmentation.py, equilibrium_median.py and dna.py.

The consequence is that PyG does not remove the implementation step. A new layer means Python, a forward signature matching x and edge_index, and a test you write. The library supplies the base class, the operators and the utility functions, not your architecture, and those examples are demonstrations rather than a registry of things you can configure.

Extras bring their own pins, and two of them hold protobuf below 4.21

The optional dependency groups are where installation trouble hides. graphgym pins protobuf<4.21 and adds pytorch-lightning and yacs. benchmark repeats protobuf<4.21 and adds matplotlib, networkx, pandas and wandb. test pulls onnx, onnxruntime, onnxscript, pytest and pytest-cov. dev adds ipython, matplotlib-inline, pre-commit and torch_geometric[test]. modelhub is a single package, huggingface_hub. rag is the outlier: faiss-cpu, json-repair, langgraph, openai, pcst_fast, PyYAML, datasets, transformers, pandas, sentencepiece, accelerate, torchmetrics and peft. full includes scipy, scikit-learn, ase, captum<0.7.0, graphviz, h5py and matplotlib, among others.

Two things follow. The upper bounds are real constraints, so protobuf<4.21 in two groups and captum<0.7.0 in full will refuse to install beside a newer protobuf or captum already present, and pulling an extra into a shared environment is where a resolver conflict starts. And the rag extra drags a language model plus vector search stack into a graph library, so installing it for retrieval work changes the dependency surface far beyond graph code. Install only the extras your task needs.

Scale is assembled from examples, not switched on

The large-graph claims are assembled rather than enabled. The highlights name scalable GNNs for graphs with millions of nodes, dynamic GNNs for node predictions over time, and heterogeneous GNNs with multiple node and edge types. The supporting pieces are described as mini-batch loaders that work on many small graphs and on a single giant graph, multi GPU support, torch.compile support, DataPipe support, and transforms for graphs, 3D meshes and point clouds.

The examples directory shows what that looks like in practice, with cluster_gcn_ppi.py, cluster_gcn_reddit.py, faust.py, and a datapipe.py file next to compile and distributed directories. None of those names is a configuration switch. Reaching a million nodes is therefore a project of your own making: you choose the sampler, the partitioning, whether to shard across GPUs or hand work to DataPipe, and whether to compile. Each choice is a script in examples/ that you adapt to your graph, not a flag on a loader.

The Cora example caches into whatever directory you launch from

Dataset loaders take a root directory you choose, and the quick tour picks your current directory for you. Cora is loaded with Planetoid(root='.', name='Cora'), so the cache path is a literal dot: wherever you happened to start the interpreter. Benchmarks are described as a large number of common datasets with simple interfaces for creating your own, and the project ships a benchmark directory, a test directory, a graphgym directory, docs, CHANGELOG.md, CITATION.cff and a codecov.yml at the root.

The consequence is an operational habit that pays for itself. Data loaded with root='.' is tied to the directory you ran from, so scripts launched from different places keep separate copies and separate state, and a read-only working directory fails on the first download. Choose one absolute root and reuse it everywhere. For questions there is a Slack community linked from the project, the documentation at pytorch-geometric.readthedocs.io, the homepage at pyg.org, and Colab notebooks for trying the tour without a local setup.

Editorial conclusion

PyG fits researchers who want published graph architectures and a tensor-centric API that stays close to PyTorch, and who are willing to choose the PyTorch build, the sampler and the extras themselves. It does not fit a shared environment that already holds a newer protobuf or captum, nor a Python older than 3.10. Before you start, install PyTorch first, pin to a release tag rather than the master branch, and pick only the extras your task needs.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes