Repository files navigation

PyG(PyTorch Geometric) is a library built uponPyTorch 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, also known asgeometric deep learning, from a variety of published papers.In addition, it consists of easy-to-use mini-batch loaders for operating on many small and single giant graphs,multi GPU-support,torch.compile support,DataPipe support, a large number of common benchmark datasets (based on simple interfaces to create your own), and helpful transforms, both for learning on arbitrary graphs as well as on 3D meshes or point clouds.

Click here to join our Slack community!

• Library Highlights
• Quick Tour for New Users
• Architecture Overview
• Implemented GNN Models
• Installation

Whether you are a machine learning researcher or first-time user of machine learning toolkits, here are some reasons to try out PyG for machine learning on graph-structured data.

• Easy-to-use and unified API:All it takes is 10-20 lines of code to get started with training a GNN model (see the next section for aquick tour).PyG isPyTorch-on-the-rocks: It utilizes a tensor-centric API and keeps design principles close to vanilla PyTorch.If you are already familiar with PyTorch, utilizing PyG is straightforward.
• Comprehensive and well-maintained GNN models:Most of the state-of-the-art Graph Neural Network architectures have been implemented by library developers or authors of research papers and are ready to be applied.
• Great flexibility:Existing PyG models can easily be extended for conducting your own research with GNNs.Making modifications to existing models or creating new architectures is simple, thanks to its easy-to-use message passing API, and a variety of operators and utility functions.
• Large-scale real-world GNN models:We focus on the need of GNN applications in challenging real-world scenarios, and support learning on diverse types of graphs, including but not limited to: scalable GNNs for graphs with millions of nodes; dynamic GNNs for node predictions over time; heterogeneous GNNs with multiple node types and edge types.

In this quick tour, we highlight the ease of creating and training a GNN model with only a few lines of code.

In the first glimpse of PyG, we implement the training of a GNN for classifying papers in a citation graph.For this, we load theCora dataset, and create a simple 2-layer GCN model using the pre-definedGCNConv:

importtorchfromtorchimportTensorfromtorch_geometric.nnimportGCNConvfromtorch_geometric.datasetsimportPlanetoiddataset=Planetoid(root='.',name='Cora')classGCN(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)defforward(self,x:Tensor,edge_index:Tensor)->Tensor:# x: Node feature matrix of shape [num_nodes, in_channels]# edge_index: Graph connectivity matrix of shape [2, num_edges]x=self.conv1(x,edge_index).relu()x=self.conv2(x,edge_index)returnxmodel=GCN(dataset.num_features,16,dataset.num_classes)

importtorch.nn.functionalasFdata=dataset[0]optimizer=torch.optim.Adam(model.parameters(),lr=0.01)forepochinrange(200):pred=model(data.x,data.edge_index)loss=F.cross_entropy(pred[data.train_mask],data.y[data.train_mask])# Backpropagationoptimizer.zero_grad()loss.backward()optimizer.step()

More information about evaluating final model performance can be found in the correspondingexample.

In addition to the easy application of existing GNNs, PyG makes it simple to implement custom Graph Neural Networks (seehere for the accompanying tutorial).For example, this is all it takes to implement theedge convolutional layer from Wanget al.:

$$x_i^{\prime} ~ = ~ \max_{j \in \mathcal{N}(i)} ~ \textrm{MLP}_{\theta} \left( [ ~ x_i, ~ x_j - x_i ~ ] \right)$$

importtorchfromtorchimportTensorfromtorch.nnimportSequential,Linear,ReLUfromtorch_geometric.nnimportMessagePassingclassEdgeConv(MessagePassing):def__init__(self,in_channels,out_channels):super().__init__(aggr="max")# "Max" aggregation.self.mlp=Sequential(Linear(2*in_channels,out_channels),ReLU(),Linear(out_channels,out_channels),        )defforward(self,x:Tensor,edge_index:Tensor)->Tensor:# x: Node feature matrix of shape [num_nodes, in_channels]# edge_index: Graph connectivity matrix of shape [2, num_edges]returnself.propagate(edge_index,x=x)# shape [num_nodes, out_channels]defmessage(self,x_j:Tensor,x_i:Tensor)->Tensor:# x_j: Source node features of shape [num_edges, in_channels]# x_i: Target node features of shape [num_edges, in_channels]edge_features=torch.cat([x_i,x_j-x_i],dim=-1)returnself.mlp(edge_features)# shape [num_edges, out_channels]

PyG provides a multi-layer framework that enables users to build Graph Neural Network solutions on both low and high levels.It comprises of the following components:

• The PyGengine utilizes the powerful PyTorch deep learning framework with fulltorch.compile andTorchScript support, as well as additions of efficient CPU/CUDA libraries for operating on sparse data,e.g.,pyg-lib.
• The PyGstorage handles data processing, transformation and loading pipelines. It is capable of handling and processing large-scale graph datasets, and provides effective solutions for heterogeneous graphs. It further provides a variety of sampling solutions, which enable training of GNNs on large-scale graphs.
• The PyGoperators bundle essential functionalities for implementing Graph Neural Networks. PyG supports important GNN building blocks that can be combined and applied to various parts of a GNN model, ensuring rich flexibility of GNN design.
• Finally, PyG provides an abundant set of GNNmodels, and examples that showcase GNN models on standard graph benchmarks. Thanks to its flexibility, users can easily build and modify custom GNN models to fit their specific needs.

We list currently supported PyG models, layers and operators according to category:

GNN layers:All Graph Neural Network layers are implemented via thenn.MessagePassing interface.A GNN layer specifies how to perform message passing,i.e. by designing different message, aggregation and update functions as definedhere.These GNN layers can be stacked together to create Graph Neural Network models.

• GCNConv from Kipf and Welling:Semi-Supervised Classification with Graph Convolutional Networks (ICLR 2017) [Example]
• ChebConv from Defferrardet al.:Convolutional Neural Networks on Graphs with Fast Localized Spectral Filtering (NIPS 2016) [Example]
• GATConv from Veličkovićet al.:Graph Attention Networks (ICLR 2018) [Example]

Pooling layers:Graph pooling layers combine the vectorial representations of a set of nodes in a graph (or a subgraph) into a single vector representation that summarizes its properties of nodes.It is commonly applied to graph-level tasks, which require combining node features into a single graph representation.

• Top-K Pooling from Gao and Ji:Graph U-Nets (ICML 2019), Cangeaet al.:Towards Sparse Hierarchical Graph Classifiers (NeurIPS-W 2018) and Knyazevet al.:Understanding Attention and Generalization in Graph Neural Networks (ICLR-W 2019) [Example]
• DiffPool from Yinget al.:Hierarchical Graph Representation Learning with Differentiable Pooling (NeurIPS 2018) [Example]

GNN models:Our supported GNN models incorporate multiple message passing layers, and users can directly use these pre-defined models to make predictions on graphs.Unlike simple stacking of GNN layers, these models could involve pre-processing, additional learnable parameters, skip connections, graph coarsening, etc.

• SchNet from Schüttet al.:SchNet: A Continuous-filter Convolutional Neural Network for Modeling Quantum Interactions (NIPS 2017) [Example]
• DimeNet andDimeNetPlusPlus from Klicperaet al.:Directional Message Passing for Molecular Graphs (ICLR 2020) andFast and Uncertainty-Aware Directional Message Passing for Non-Equilibrium Molecules (NeurIPS-W 2020) [Example]
• Node2Vec from Grover and Leskovec:node2vec: Scalable Feature Learning for Networks (KDD 2016) [Example]
• Deep Graph Infomax from Veličkovićet al.:Deep Graph Infomax (ICLR 2019) [Example1,Example2]
• Deep Multiplex Graph Infomax from Parket al.:Unsupervised Attributed Multiplex Network Embedding (AAAI 2020) [Example]
• Masked Label Prediction from Shiet al.:Masked Label Prediction: Unified Message Passing Model for Semi-Supervised Classification (CoRR 2020) [Example]
• PMLP from Yanget al.:Graph Neural Networks are Inherently Good Generalizers: Insights by Bridging GNNs and MLPs (ICLR 2023)

GNN operators and utilities:PyG comes with a rich set of neural network operators that are commonly used in many GNN models.They follow an extensible design: It is easy to apply these operators and graph utilities to existing GNN layers and models to further enhance model performance.

• DropEdge from Ronget al.:DropEdge: Towards Deep Graph Convolutional Networks on Node Classification (ICLR 2020)
• DropNode,MaskFeature andAddRandomEdge from Youet al.:Graph Contrastive Learning with Augmentations (NeurIPS 2020)
• DropPath from Liet al.:MaskGAE: Masked Graph Modeling Meets Graph Autoencoders (arXiv 2022)
• ShuffleNode from Veličkovićet al.:Deep Graph Infomax (ICLR 2019)
• GraphNorm from Caiet al.:GraphNorm: A Principled Approach to Accelerating Graph Neural Network Training (ICML 2021)
• GDC from Klicperaet al.:Diffusion Improves Graph Learning (NeurIPS 2019) [Example]

Scalable GNNs:PyG supports the implementation of Graph Neural Networks that can scale to large-scale graphs.Such application is challenging since the entire graph, its associated features and the GNN parameters cannot fit into GPU memory.Many state-of-the-art scalability approaches tackle this challenge by sampling neighborhoods for mini-batch training, graph clustering and partitioning, or by using simplified GNN models.These approaches have been implemented in PyG, and can benefit from the above GNN layers, operators and models.

• NeighborLoader from Hamiltonet al.:Inductive Representation Learning on Large Graphs (NIPS 2017) [Example1,Example2,Example3]
• ClusterGCN from Chianget al.:Cluster-GCN: An Efficient Algorithm for Training Deep and Large Graph Convolutional Networks (KDD 2019) [Example1,Example2]
• GraphSAINT from Zenget al.:GraphSAINT: Graph Sampling Based Inductive Learning Method (ICLR 2020) [Example]

PyG is available for Python 3.10 to Python 3.13.

FromPyG 2.3 onwards, you can install and use PyGwithout any external library required except for PyTorch.For this, simply run

pip install torch_geometric

If you want to utilize the full set of features from PyG, there exists several additional libraries you may want to install:

• pyg-lib: Heterogeneous GNN operators and graph sampling routines
• torch-scatter: Accelerated and efficient sparse reductions
• torch-sparse:SparseTensor support
• torch-cluster: Graph clustering routines
• torch-spline-conv:SplineConv support

These packages come with their own CPU and GPU kernel implementations based on thePyTorch C++/CUDA/hip(ROCm) extension interface.For a basic usage of PyG, these dependencies arefully optional.We recommend to start with a minimal installation, and install additional dependencies once you start to actually need them.

For ease of installation of these extensions, we providepip wheels for all major OS/PyTorch/CUDA combinations, seehere.

To install the binaries for PyTorch 2.8.0, simply run

pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.8.0+${CUDA}.html

where${CUDA} should be replaced by eithercpu,cu126,cu128, orcu129 depending on your PyTorch installation.

To install the binaries for PyTorch 2.7.0, simply run

pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.7.0+${CUDA}.html

where${CUDA} should be replaced by eithercpu,cu118,cu126, orcu128 depending on your PyTorch installation.

To install the binaries for PyTorch 2.6.0, simply run

pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.6.0+${CUDA}.html

where${CUDA} should be replaced by eithercpu,cu118,cu124, orcu126 depending on your PyTorch installation.

Note: Binaries of older versions are also provided for PyTorch 1.4.0, PyTorch 1.5.0, PyTorch 1.6.0, PyTorch 1.7.0/1.7.1, PyTorch 1.8.0/1.8.1, PyTorch 1.9.0, PyTorch 1.10.0/1.10.1/1.10.2, PyTorch 1.11.0, PyTorch 1.12.0/1.12.1, PyTorch 1.13.0/1.13.1, PyTorch 2.0.0/2.0.1, PyTorch 2.1.0/2.1.1/2.1.2, PyTorch 2.2.0/2.2.1/2.2.2, PyTorch 2.3.0/2.3.1, PyTorch 2.4.0/2.4.1, and PyTorch 2.5.0/2.5.1 (following the same procedure).For older versions, you might need to explicitly specify the latest supported version number or install viapip install --no-index in order to prevent a manual installation from source.You can look up the latest supported version numberhere.

NVIDIA provides a PyG docker container for effortlessly training and deploying GPU accelerated GNNs with PyG, seehere.

In case you want to experiment with the latest PyG features which are not fully released yet, either install thenightly version of PyG via

pip install pyg-nightly

or install PyGfrom master via

pip install git+https://github.com/pyg-team/pytorch_geometric.git

The externalpyg-rocm-build repository provides wheels and detailed instructions on how to install PyG for ROCm.If you have any questions about it, please open an issuehere.

Please cite ourPyG 1.0 andPyG 2.0 papers if you use this code in your own work:

@inproceedings{Fey/Lenssen/2019,  title={Fast Graph Representation Learning with {PyTorch Geometric}},  author={Fey, Matthias and Lenssen, Jan E.},  booktitle={ICLR Workshop on Representation Learning on Graphs and Manifolds},  year={2019},}@inproceedings{Fey/etal/2025,  title={{PyG} 2.0: Scalable Learning on Real World Graphs},  author={Fey, Matthias and Sunil, Jinu and Nitta, Akihiro and Puri, Rishi and Shah, Manan, and Stojanovi{\v{c}, Bla{\v{z} and Bendias, Ramona and Alexandria, Barghi and Kocijan, Vid and Zhang, Zecheng and He, Xinwei and Lenssen, Jan E. and Leskovec, Jure},  booktitle={Temporal Graph Learning Workshop @ KDD},  year={2025},}

Feel free toemail us if you wish your work to be listed in theexternal resources.If you notice anything unexpected, please open anissue and let us know.If you have any questions or are missing a specific feature, feel freeto discuss them with us.We are motivated to constantly make PyG even better.