PyTorch Geometric: a GNN library built on PyTorch tensors

What PyTorch Geometric is for, and who it is for

PyG exists because ordinary PyTorch layers assume a fixed grid. A convolution over an image indexes neighbours by offset; a graph has no such offsets, only an edge list. The library supplies the missing abstraction: message passing layers that take a node feature matrix and an edge_index tensor and return updated node features. The README frames the audience as machine learning researchers and first-time users of ML toolkits, and the pyproject classifiers mark the project Production/Stable with support for Python 3.10 through 3.14.

The concrete use cases named in the README are broad: citation graphs for paper classification, 3D meshes, point clouds, dynamic graphs for node prediction over time, and heterogeneous graphs with multiple node and edge types. If your problem is 'nodes have features, nodes have relationships, I want to predict something about nodes or edges', that is the target. If your problem is 'I want the shortest path between two cities', it is not.

How message passing and the edge_index tensor work together

The unit of data in PyG is a Data object holding x (node features) and edge_index (connectivity). The README comments describe x as shape [num_nodes, in_channels] and edge_index as the graph connectivity matrix. Every convolution layer consumes both and produces a new x.

GCNConv is the simplest example. A custom layer subclasses MessagePassing and declares an aggregation scheme in the constructor, for instance aggr="max" in the EdgeConv example the README gives. The layer implements forward, which calls propagate with the edge_index, and the base class handles the scatter and gather. This is why the README calls the API tensor-centric and says it keeps design principles close to vanilla PyTorch: there is no separate graph runtime, only tensors and a message passing loop.

Around that core sit the pieces that make it usable at scale. Mini-batch loaders handle many small graphs or one giant graph; the README also lists multi-GPU support, torch.compile support and DataPipe support. Datasets are exposed through a common interface, with Planetoid, and the README links to a large set of benchmark datasets. GraphGym, a separate top-level directory in the repository, targets graph learning experimentation, and it is installed through an optional dependency group rather than the base install.

Installing PyTorch Geometric and running the Cora example

The package name on PyPI is torch-geometric, not pytorch-geometric. The README points to the documentation for installation; the version in pyproject.toml is 2.9.0 and requires Python 3.10 or newer. The base install pulls aiohttp, fsspec, jinja2, numpy, psutil, pyparsing, requests, tqdm and xxhash, and does not include scipy, scikit-learn or matplotlib, which live in the full extra.

pip install torch-geometric

After that, load a dataset and build a two-layer GCN. The README's quick tour downloads Cora into the current directory and defines the model:

import torch
from torch import Tensor
from torch_geometric.nn import GCNConv
from torch_geometric.datasets import Planetoid

dataset = Planetoid(root='.', name='Cora')

class GCN(torch.nn.Module):
    def __init__(self, in_channels, hidden_channels, out_channels):
        super().__init__()
        self.conv1 = GCNConv(in_channels, hidden_channels)
        self.conv2 = GCNConv(hidden_channels, out_channels)

The training loop is ordinary PyTorch. The README optimizes with Adam at lr=0.01 for 200 epochs and computes cross entropy only over the training mask, which is the part that differs from image training:

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])

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

Expect a loss that falls over the 200 epochs. The README says the full evaluation code lives in examples/gcn.py, and the repository also ships examples/cora.py, which is the closer match if you want a runnable file rather than a snippet.

Where PyTorch Geometric stops being the right tool

The first limitation is documentation depth. The README is a tour, not a manual. It shows how to define a layer and train on a dataset that already exists, then links out for anything else. There is no worked example of writing a custom InMemoryDataset subclass or of debugging a loader that silently returns the wrong number of neighbours. Expect to read the readthedocs site.

The second is the dependency surface. The base install is deliberately small, but the optional groups are not: the rag extra alone pulls faiss-cpu, langgraph, openai, transformers, sentencepiece, accelerate, peft and torchmetrics, and the full extra adds scipy, scikit-learn, ase, captum, graphviz, h5py and matplotlib. Installing torch_geometric[full] to get scipy is a heavy way to obtain one numerical library.

Third, this is not a graph analysis library. If you want connected components, centrality or shortest paths, you are paying for a GPU tensor stack to do work that a pure Python library does faster to write. And if your graph fits in memory as a small adjacency structure and you only need a few hand-written features, a GNN may not beat a simple baseline at all; the README makes no accuracy claim for any model, so the comparison is yours to run.

PyTorch Geometric versus DGL, NetworkX and plain PyTorch

The most common comparison is against Deep Graph Library, usually abbreviated DGL. Both provide message passing on top of a tensor framework, but the framing differs. PyG's stated design principle is to stay close to vanilla PyTorch, with a tensor-centric API and an edge_index representation, so a PyG model is a torch.nn.Module that you can drop into an existing PyTorch training loop, which is exactly what the Cora snippet does. DGL's surface is built around its own graph object, so the code you write is recognizably DGL code rather than PyTorch code. If your team's debugging habits, checkpointing and distributed training are already PyTorch-shaped, that difference decides the choice.

Against NetworkX the split is cleaner. NetworkX is a graph algorithm library for CPU work: it does not train anything. Use it to inspect a graph, compute degree distributions or check connectivity before you decide whether a GNN is worth training. The two are complementary, not competing.

Against plain PyTorch, the honest answer is that PyG is plain PyTorch plus a scatter operation. You could implement GCNConv yourself in an afternoon. What you would not get is the collection of published architectures, the loaders for many small graphs and single giant graphs, and the Planetoid and other benchmark datasets behind one interface. That collection, not the math, is what you are installing.

Maintenance, licence and the cost of upgrading

The repository is not archived. The last push was on 2026-06-05, which is the same date as the 2.8.0 release, so the project is active but not on a fast cadence: the previous release, 2.7.0, landed on 2025-10-14, and 2.6.1 before that on 2024-09-26. The version field in pyproject.toml reads 2.9.0, ahead of the latest tagged release, which is normal for a development branch.

That cadence matters for planning. Roughly one or two releases a year means an upgrade is an event you schedule, not a background pip upgrade. The practical risk is the torch pairing: torch-geometric sits on top of PyTorch, so a torch upgrade and a torch-geometric upgrade are usually the same ticket. Read CHANGELOG.md before moving, and keep the torch version pinned in the same environment file.

The licence is MIT, declared both in pyproject.toml and in the LICENSE file at the repository root. MIT is permissive: it allows commercial use and modification with attribution and no warranty. This is a description of the licence text, not legal advice; if your organisation has a policy on bundled dependencies, note that the optional extras pull in packages with their own licences, including protobuf, pytorch-lightning and the rag stack.

Editorial conclusion

Adopt PyTorch Geometric if your team already writes PyTorch and your data is a graph rather than a grid: the GCNConv and Planetoid quick tour in the README is a working starting point in under twenty lines. Do not adopt it if you only need classical graph algorithms, since NetworkX covers shortest paths and centrality without a tensor runtime, and do not expect the README to walk you through custom dataset classes, because it points to the documentation instead. Before committing, check that your Python version is 3.10 or newer and that the torch build you have installed matches the one torch-geometric was resolved against, then run the Cora example in examples/cora.py to confirm the wheel loads.

Frequently asked questions

Official sources

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