Installation

PyG is available for Python 3.7 to Python 3.10.

Note

We do not recommend installation as a root user on your system Python. Please setup a Anaconda or Miniconda environment or create a Docker image.

Quick Start

PyTorch

Your OS

Package

CUDA

Run:

Installation via Anaconda

Update: You can now install PyG via Anaconda for all major OS/PyTorch/CUDA combinations 🤗 Given that you have PyTorch >= 1.8.0 installed, simply run

conda install pyg -c pyg

Installation via Pip Wheels

We have outsourced a lot of functionality of PyG to other packages, which needs to be installed in advance. These packages come with their own CPU and GPU kernel implementations based on the PyTorch C++/CUDA extension interface. We provide pip wheels for these packages for all major OS/PyTorch/CUDA combinations, see here:

1. Ensure that at least PyTorch 1.12.0 is installed:

   python -c "import torch; print(torch.__version__)"
   >>> 1.13.0
   

2. Find the CUDA version PyTorch was installed with:

   python -c "import torch; print(torch.version.cuda)"
   >>> 11.6
   

3. Install the relevant packages:

   pip install pyg-lib torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html
   pip install torch-geometric
   

   where ${CUDA} and ${TORCH} should be replaced by the specific CUDA version (e.g., cpu, cu116, or cu117 for PyTorch 1.13, and cpu, cu102, cu113, or 116 for PyTorch 1.12) and PyTorch version (1.11.0, 1.12.0), respectively. For example, for PyTorch 1.13.* and CUDA 11.6, type:

   pip install pyg-lib torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-1.13.0+cu116.html
   pip install torch-geometric
   

   For PyTorch 1.12.* and CUDA 11.3, type:

   pip install pyg-lib torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-1.12.0+cu113.html
   pip install torch-geometric
   

4. Install additional packages (optional):

   To add additional functionality to PyG, such as k-NN and radius graph generation or SplineConv support, run

   pip install torch-cluster torch-spline-conv -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html
   

   following the same procedure as mentioned above.

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,a nd PyTorch 1.11.0 (following the same procedure). For older versions, you need to explicitly specify the latest supported version number or install via pip install --no-index in order to prevent a manual installation from source. You can look up the latest supported version number here.

Installation from Source

In case a specific version is not supported by our wheels, you can alternatively install PyG from source:

1. Ensure that your CUDA is setup correctly (optional):

   1. Check if PyTorch is installed with CUDA support:

      python -c "import torch; print(torch.cuda.is_available())"
      >>> True
      

   2. Add CUDA to $PATH and $CPATH (note that your actual CUDA path may vary from /usr/local/cuda):

      export PATH=/usr/local/cuda/bin:$PATH
      echo $PATH
      >>> /usr/local/cuda/bin:...
      
      export CPATH=/usr/local/cuda/include:$CPATH
      echo $CPATH
      >>> /usr/local/cuda/include:...
      

   3. Add CUDA to $LD_LIBRARY_PATH on Linux and to $DYLD_LIBRARY_PATH on macOS (note that your actual CUDA path may vary from /usr/local/cuda):

      export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
      echo $LD_LIBRARY_PATH
      >>> /usr/local/cuda/lib64:...
      
      export DYLD_LIBRARY_PATH=/usr/local/cuda/lib:$DYLD_LIBRARY_PATH
      echo $DYLD_LIBRARY_PATH
      >>> /usr/local/cuda/lib:...
      

   4. Verify that nvcc is accessible from terminal:

      nvcc --version
      >>> 11.3
      

   5. Ensure that PyTorch and system CUDA versions match:

      python -c "import torch; print(torch.version.cuda)"
      >>> 11.3
      
      nvcc --version
      >>> 11.3
      

2. Install the relevant packages:

   pip install pyg-lib
   pip install torch-scatter
   pip install torch-sparse
   pip install torch-geometric
   

3. Install additional packages (optional):

   pip install torch-cluster
   pip install torch-spline-conv
   

In rare cases, CUDA or Python path problems can prevent a successful installation. pip may even signal a successful installation, but runtime errors complain about missing modules, .e.g., No module named 'torch_*.*_cuda', or execution simply crashes with Segmentation fault (core dumped). We collected a lot of common installation errors in the Frequently Asked Questions subsection. In case the FAQ does not help you in solving your problem, please create an issue. You should additionally verify that your CUDA is set up correctly by following the official installation guide, and that the official extension example runs on your machine.

Frequently Asked Questions

1. ImportError: ***: cannot open shared object file: No such file or directory: Add CUDA to your $LD_LIBRARY_PATH (see Issue#43).

2. undefined symbol:, e.g. _ZN2at6detail20DynamicCUDAInterface10set_deviceE: Clear the pip cache and reinstall the respective package (see Issue#7). On macOS, it may help to install clang compilers via conda (see Issue#18):

   $ conda install -y clang_osx-64 clangxx_osx-64 gfortran_osx-64
   

3. Unable to import *_cuda: You need to import torch first before importing any of the extension packages (see Issue#6).

4. error: command '/usr/bin/nvcc' failed with exit status 2: Ensure that at least CUDA >= 8 is installed (see Issue#25a and Issue#106).

5. return __and_<is_constructible<_Elements, _UElements&&>...>::value: Ensure that your gcc version is at least 4.9 (and below 6) (see Issue#25b). You will also need to reinstall PyTorch because gcc versions must be consistent across all PyTorch packages.

6. file not recognized: file format not recognized: Clean the repository and temporarily rename Anaconda’s ld linker (see Issue#16683).

7. undefined symbol: __cudaPopCallConfiguration: Ensure that your PyTorch CUDA version and system CUDA version match (see Issue#19):

   $ python -c "import torch; print(torch.version.cuda)"
   $ nvcc --version
   

8. undefined symbol: _ZN3c105ErrorC1ENS_14SourceLocationERKSs: The std::string abi does not match between building PyTorch and its extensions. This is fixable by building extensions with -D_GLIBCXX_USE_CXX11_ABI=1 or building PyTorch from source (see this PyTorch thread).

9. On macOS: 'gcc' failed with exit status 1: Install the respective packages by using the following environment variables (see Issue#21):

   $ MACOSX_DEPLOYMENT_TARGET=10.9 CC=clang CXX=clang++ python -m pip install .
   

10. On macOS: ld: warning: directory not found for option '-L/usr/local/cuda/lib64' and ld: library not found for -lcudart: Symlink cuda/lib to cuda/lib64 (see Issue#116):

    $ sudo ln -s /usr/local/cuda/lib /usr/local/cuda/lib64
    

11. On macOS: The version of the host compiler ('Apple clang') is not supported: Downgrade your command line tools (see this StackOverflow thread) with the respective version annotated in the CUDA Installation Guide for Mac (Section 1.1) for your specific CUDA version. You can download previous command line tool versions here.

12. On Linux: nvcc fatal: Path to libdevice library not specified: This error may appear even if LD_LIBRARY_PATH and CPATH are set up correctly. As recommended by this post, the library will be found if $CUDA_HOME is defined:

    $ export CUDA_HOME=/usr/local/cuda