PyTorch Geometric (PyG)

2.7.0 · active · verified Sat Apr 11

PyTorch Geometric (PyG) is a library built upon PyTorch to easily write and train Graph Neural Networks (GNNs) for a wide range of applications related to structured data. It consists of various methods for deep learning on graphs and other irregular structures, providing easy-to-use mini-batch loaders, multi-GPU support, `torch.compile` support, a large number of common benchmark datasets, and helpful transforms. It is actively maintained with frequent minor releases delivering new features and bug fixes.

Warnings

breaking PyG 2.7.0 dropped support for Python 3.9 and PyTorch versions 1.11 through 2.5. Ensure your environment uses Python >=3.10 and PyTorch >=2.6 for compatibility.
Fix: Upgrade Python to 3.10 or newer, and PyTorch to 2.6 or newer. Check the official PyG installation guide for specific PyTorch/CUDA compatibility tables.
gotcha Installation of optional C++/CUDA extensions (e.g., `torch-scatter`, `torch-sparse`) is complex and requires careful matching of PyTorch and CUDA versions, often necessitating specific pre-built wheels. Mismatched versions can lead to compilation errors or runtime issues.
Fix: Always refer to the official PyTorch Geometric installation instructions. Use the provided `-f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html` link, replacing `${TORCH}` and `${CUDA}` placeholders with your exact PyTorch and CUDA versions.
deprecated The `torch_geometric.compile` utility and `MessagePassing.jittable` attribute have been deprecated. Users should migrate to `torch.compile` for model optimization.
Fix: Replace usages of `torch_geometric.compile(model)` with `torch.compile(model)`. Remove `jittable=True` from `MessagePassing` layer initializations if present.
breaking The interface and implementation of `GraphMultisetTransformer` changed in PyG 2.7.0, potentially affecting existing models that use this layer.
Fix: Review the updated documentation for `GraphMultisetTransformer` and adjust your model's implementation accordingly.

Install

pip install torch_geometric Minimal Installation
# Ensure PyTorch is installed with appropriate CUDA support, e.g., for CUDA 12.1: pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # Then install PyG's optional C++/CUDA extensions (replace TORCH and CUDA with your versions): pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html With Optional C++/CUDA Extensions

Imports

Data
```
from torch_geometric.data import Data
```
The primary object for representing a single graph.
MessagePassing
```
from torch_geometric.nn import MessagePassing
```
Base class for implementing custom Graph Neural Network layers.
GCNConv
```
from torch_geometric.nn import GCNConv
```
A common Graph Convolutional Network layer.
Planetoid
```
from torch_geometric.datasets import Planetoid
```
For loading benchmark graph datasets like Cora, CiteSeer, PubMed.
T
```
import torch_geometric.transforms as T
```
For graph transformations and augmentations.

Quickstart

This example demonstrates how to create a basic graph using PyTorch Geometric's `Data` object, which is the fundamental building block for representing graphs. It defines node features and graph connectivity (edges) and then prints basic properties of the created graph.

import torch
from torch_geometric.data import Data

# Define an edge list (COO format: [source_nodes, target_nodes])
edge_index = torch.tensor([[0, 1, 1, 2],
                           [1, 0, 2, 1]], dtype=torch.long)

# Define node features (3 nodes, 1 feature per node)
x = torch.tensor([[-1],
                  [0],
                  [1]], dtype=torch.float)

# Create a Data object to represent the graph
data = Data(x=x, edge_index=edge_index)

print(data)
print(f"Number of nodes: {data.num_nodes}")
print(f"Number of edges: {data.num_edges}")
print(f"Is undirected: {data.is_undirected()}")

view raw JSON →