Install PyTorch Geometric Guide

PyTorch Geometric (PyG) is a powerful library for deep learning on graphs. It extends PyTorch with tools for graph neural networks. Installing it can be tricky due to dependencies. This guide walks you through the process step by step.

We cover Linux, Windows, and macOS. You will learn to install PyTorch first, then PyG and its dependencies. Follow along with code examples and outputs.

Prerequisites

Before installing PyTorch Geometric, you need Python 3.7 or higher. You also need a package manager like pip or conda. A CUDA-capable GPU is optional but recommended for faster training.

Check your Python version:

python --version

Output should be something like:

Python 3.9.7

Step 1: Install PyTorch

PyTorch Geometric depends on PyTorch. Install the correct version of PyTorch for your system. Visit pytorch.org to get the right command.

For CPU-only installation:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

For CUDA 11.8 (common for GPU users):

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

Verify the installation:

import torch
print(torch.__version__)
print(torch.cuda.is_available())

Output example:

2.1.0
True

If torch.cuda.is_available() returns True, your GPU is ready.

Step 2: Install PyTorch Geometric Dependencies

PyG requires three core packages: torch-scatter, torch-sparse, torch-cluster, and torch-spline-conv. These are compiled for your specific PyTorch and CUDA versions.

Find your PyTorch version and CUDA version:

import torch
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA version: {torch.version.cuda}")

Output:

PyTorch version: 2.1.0
CUDA version: 11.8

Visit the PyG wheel page to find matching wheels. For PyTorch 2.1.0 with CUDA 11.8, use:

pip install torch-scatter torch-sparse torch-cluster torch-spline-conv -f https://data.pyg.org/whl/torch-2.1.0+cu118.html

For CPU-only with PyTorch 2.1.0:

pip install torch-scatter torch-sparse torch-cluster torch-spline-conv -f https://data.pyg.org/whl/torch-2.1.0+cpu.html

Wait for compilation. It may take a few minutes.

Step 3: Install PyTorch Geometric

Now install the main PyG package:

pip install torch-geometric

This installs the library without extra dependencies. If you need graph visualization tools, add pyg-lib:

pip install pyg-lib -f https://data.pyg.org/whl/torch-2.1.0+cu118.html

Step 4: Verify Installation

Test PyG with a simple script:

import torch_geometric
from torch_geometric.data import Data

# Create a simple graph with 3 nodes and 2 edges
edge_index = torch.tensor([[0, 1, 1, 2],
                           [1, 0, 2, 1]], dtype=torch.long)
x = torch.tensor([[-1], [0], [1]], dtype=torch.float)

data = Data(x=x, edge_index=edge_index)
print(data)

Expected output:

Data(x=[3, 1], edge_index=[2, 4])

This confirms PyG is working.

Common Installation Issues

Problem: Version mismatch between PyTorch and PyG wheels. Always match the wheel URL to your PyTorch version. For example, if you have PyTorch 2.0.1, use torch-2.0.1 in the URL.

Problem: Out of memory during compilation on Windows. Use a precompiled wheel from the PyG site. Alternatively, install via conda:

conda install pyg -c pyg

Problem: Missing C++ compiler on Windows. Install Microsoft Visual C++ Build Tools from here.

If you are working on graph neural networks, you might find our guide on Graph Neural Network Basics helpful. Also check PyTorch Installation Tips for more details.

Installing on macOS

macOS users often face issues with CUDA. PyTorch for macOS does not support CUDA. Use CPU-only installation:

pip install torch torchvision torchaudio
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv -f https://data.pyg.org/whl/torch-2.1.0+cpu.html
pip install torch-geometric

Test with the same script as above. It will run on CPU.

Installing on Windows

Windows requires extra care. Use pip with the correct wheel URL. For CUDA 11.8 and PyTorch 2.1.0:

pip install torch-scatter torch-sparse torch-cluster torch-spline-conv -f https://data.pyg.org/whl/torch-2.1.0+cu118.html
pip install torch-geometric

If you get a "No module named 'torch'" error, ensure PyTorch is installed first. You can also use conda on Windows for smoother setup.

Using Conda (Alternative)

Conda simplifies dependencies. Create a new environment and install PyG:

conda create -n pyg_env python=3.9
conda activate pyg_env
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia
conda install pyg -c pyg

This method avoids compilation issues.

Conclusion

Installing PyTorch Geometric requires matching versions of PyTorch and its dependencies. Follow the steps for your OS and hardware. Verify with a simple graph data object. If you face issues, use conda or precompiled wheels.

With PyG installed, you can build graph neural networks for tasks like node classification and link prediction. For more advanced examples, see our Graph Neural Network Tutorial.