【PyTorch】PyTorch Geometric（PyG）安装指南：如何高效配置图神经网络环境

引言

PyTorch Geometric（PyG）是一个强大的图神经网络（GNN）库，基于 PyTorch 进行构建，专门用于处理图数据的深度学习任务。随着图神经网络在图像处理、社交网络分析、推荐系统等领域的广泛应用，PyG 成为许多研究人员和开发者的首选工具之一。通过 PyG，你可以轻松地实现图卷积、图采样、图分类等复杂操作，从而构建出更为高效和准确的图神经网络模型。

然而，安装 PyTorch Geometric 可能会因为系统配置、依赖库版本或硬件环境的不同而变得复杂。为了帮助你顺利安装 PyG，并确保你的环境准备工作无误，本博客将为你提供多种安装方法，并详细介绍如何通过 Anaconda、PyPi、源代码等方式进行安装。同时，我们还将讨论如何解决安装过程中常见的错误，确保你能够快速、顺利地开始你的图神经网络之旅。

支持的 Python 版本

• Python 3.9 到 3.12 是 PyTorch Geometric 当前支持的版本。
• 如果你正在使用 Python 3.8 或更低版本，建议升级 Python 版本以确保兼容性。

一、通过 Anaconda 安装

PyG 现在支持通过 Anaconda 在所有主流操作系统、PyTorch 和 CUDA 的组合上进行安装。如果你还没有安装 PyTorch，请参考 PyTorch 官方文档 通过 conda 安装 PyTorch。确保你安装的 PyTorch 版本至少是 1.11.0。安装完成后，可以通过以下命令安装 PyG：

安装步骤：

1. 安装 PyTorch

   首先，确保你已经安装了 PyTorch。你可以使用以下命令通过 Anaconda 安装 PyTorch：

   conda install pytorch -c pytorch
   

   如果你希望在 CUDA 上进行加速，确保选择相应的 CUDA 版本。例如，安装支持 CUDA 11.8 的 PyTorch：

   conda install pytorch cudatoolkit=11.8 -c pytorch
   

2. 安装 PyTorch Geometric

   安装完 PyTorch 后，可以通过以下命令来安装 PyTorch Geometric：

   conda install pyg -c pyg
   

   注意：目前，Conda 包在 Windows 和 M1/M2/M3 Mac 上不可用。如果你是 Windows 或 Mac 用户，建议使用 pip 安装。

3. 指定 CUDA 版本

   如果 Conda 安装时未正确识别你系统的 CUDA 版本，你可以通过显式指定 CUDA 版本来进行安装。命令如下：

   conda install pyg=*=*cu* -c pyg
   

这个命令的作用是安装 pyg（例如 PyTorch Geometric）并指定相关的 CUDA 版本。我们可以进一步解析命令中的参数。

• pyg=*=*cu*：此部分用于指定需要安装的库及其版本。

  • pyg 是指需要安装的包名称，这里假设是 PyTorch Geometric（根据你的环境，包名称可能会有所不同）。
  • =* 表示匹配所有版本。
  • *cu* 用于指定 CUDA 版本（其中 *cu* 表示匹配包含 CUDA 支持的包版本，CUDA 版本会自动跟随选择）。

• -c pyg：此参数指定了安装包的来源（频道），这里是 pyg 频道。你可以通过替换为其他合法频道来选择包源。

指定 CUDA 版本的实际示例：

假设你需要安装 PyTorch Geometric（pyg），并且你希望使用特定版本的 PyTorch（例如 1.13.0）以及特定的 CUDA 版本（例如 CUDA 11.7）。你可以通过以下命令显式指定所需的 CUDA 版本：

conda install pyg=2.2.0=pygcu117 -c pyg -c pytorch

命令解析：

• pyg=2.2.0：指定安装 PyTorch Geometric 版本 2.2.0。
• pygcu117：指定与 CUDA 11.7 兼容的版本。在 pyg 包中，cu117 表示与 CUDA 11.7 兼容的构建版本。注意，PyTorch 和 PyTorch Geometric 等包通常会有多个与不同 CUDA 版本兼容的版本。
• -c pyg：指定使用 PyTorch Geometric 频道来获取包。
• -c pytorch：指定使用 PyTorch 频道来获取 PyTorch 和其他相关依赖。

二、通过 PyPi 安装

如果你使用 pip 而非 conda，你可以直接通过 PyPi 安装 PyTorch Geometric。

安装步骤：

1. 安装 PyTorch

   在使用 PyG 之前，确保已经安装了 PyTorch。可以通过以下命令进行安装：

   pip install torch
   

2. 安装 PyTorch Geometric

   从 PyG 2.3 版本开始，你可以仅通过 PyTorch 安装和使用 PyG，无需额外的外部库。只需运行以下命令：

   pip install torch_geometric
   

   这种方式会自动安装必要的依赖，并且适合大多数用户。

安装额外的库

PyTorch Geometric 提供了一些额外的库来扩展图神经网络的功能，尤其是在大规模图和复杂模型训练时提供了各种加速和优化操作。以下是一些推荐的库：

库名	描述
pyg-lib	支持异构图神经网络（Heterogeneous GNNs）和图采样功能。
torch-scatter	高效的稀疏矩阵归约操作，广泛用于稀疏数据的图处理。
torch-sparse	提供支持稀疏张量的操作，提升计算效率。
torch-cluster	实现高效的图聚类操作，适用于图的分区和聚类任务。
torch-spline-conv	支持基于样条的卷积（SplineConv）操作，用于图中的边际学习。

这些库能够提升图神经网络训练的效率和灵活性。如果你希望在使用 PyG 时充分发挥其性能，可以考虑安装这些额外的库：

pip install pyg-lib torch-scatter torch-sparse torch-cluster torch-spline-conv

这些库自带 CPU 和 GPU 内核实现，基于 PyTorch 的 C++/CUDA/hip(ROCm) 扩展接口。如果你刚开始使用 PyG，可以从最小安装开始，待实际需要时再安装额外的依赖库。

三、从 Wheels 安装

为了简化依赖库的安装过程，PyTorch Geometric 提供了多种预构建的 wheel 包，这些包支持多种操作系统、PyTorch 和 CUDA 版本的组合。你可以访问 PyG Wheel 下载页面 来选择与你的环境相匹配的版本。

警告：目前 M1/M2/M3 的 Mac 不支持使用 Wheels 安装。请从源代码安装扩展包。

检查 PyTorch 版本和 CUDA 版本

在安装 PyG 的额外依赖之前，需要确保你使用的 PyTorch 版本和 CUDA 版本正确，请确保你的 PyTorch 版本至少是 1.13.0。你可以通过以下命令检查：

python -c "import torch; print(torch.__version__)"
>>> 2.5.0  # 例如，显示 PyTorch 版本python -c "import torch; print(torch.version.cuda)"
>>> 12.4  # 显示 CUDA 版本

如果你已经安装了合适的 PyTorch 版本（例如，PyTorch 2.5.0 和 CUDA 12.4），可以使用如下命令安装相关依赖库：

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

其中 ${TORCH} 和 ${CUDA} 需要根据你的实际版本替换为你当前使用的 PyTorch 和 CUDA 版本。其中 ${TORCH} 和 ${CUDA} 应该被具体替换PyTorch和 CUDA 版本分别为：

• PyTorch2.4: ${TORCH}=2.5.0 和 ${CUDA}=cpu|cu118|cu121|cu124
• PyTorch2.4: ${TORCH}=2.4.0 和 ${CUDA}=cpu|cu118|cu121|cu124
• PyTorch2.3: ${TORCH}=2.3.0 和 ${CUDA}=cpu|cu118|cu121
• PyTorch2.2: ${TORCH}=2.2.0 和 ${CUDA}=cpu|cu118|cu121
• PyTorch2.1: ${TORCH}=2.1.0 和 ${CUDA}=cpu|cu118|cu121
• PyTorch2.0: ${TORCH}=2.0.0 和 ${CUDA}=cpu|cu117|cu118
• PyTorch1.13: ${TORCH}=1.13.0 和 ${CUDA}=cpu|cu116|cu117

例如：

• 对于 PyTorch 2.5 和 CUDA 12.4：

  pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.5.0+cu124.html
  

• 对于 PyTorch 2.4 和 CUDA 11.8：

  pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.4.0+cu118.html
  

以下是一些常见的版本组合：

PyTorch 版本	CUDA 版本	下载链接
2.5.0	cu124	https://data.pyg.org/whl/torch-2.5.0+cu124.html
2.4.0	cu118	https://data.pyg.org/whl/torch-2.4.0+cu118.html
2.3.0	cu121	https://data.pyg.org/whl/torch-2.3.0+cu121.html
2.2.0	cu118	https://data.pyg.org/whl/torch-2.2.0+cu118.html
2.0.0	cu117	https://data.pyg.org/whl/torch-2.0.0+cu117.html
1.13.0	cu116	https://data.pyg.org/whl/torch-1.13.0+cu116.html

注意：还提供了旧版本的二进制文件PyTorch1.4.0、1.5.0、1.6.0、1.7.0/1.7.1、1.8.0/1.8.1、1.9.0、1.10.0/1.10.1/1.10.2、1.11.0、1.12.0/1.12.1、1.13.0/1.13.1、2.0.0/2.0.1、2.1.0/2.1.1/2.1.2、2.2.0/2.2.1/2.2.2 和 2.3.0/2.3.1（按照相同的程序）。对于较旧的版本，您需要明确指定最新支持的版本号或通过安装，以防止从源手动安装。您可以在此处查找最新支持的版本号。

pip install --no-index

四、从 ROCm 安装

如果你使用的是 ROCm 平台，可以参考 pyg-rocm-build 存储库，这里提供了 PyTorch Geometric 相关的轮子包（Whl 文件）和安装详细说明。你可以根据该文档中的步骤进行安装。

如果你在安装过程中遇到问题，欢迎在 GitHub Issues 提出问题，我们会尽快解决。

五、从源代码安装

如果你发现我们的轮子包无法满足你的需求（例如，某些版本不支持），你可以选择从源代码进行安装。以下是从源代码安装的详细步骤。

5.1 确保 CUDA 环境设置正确

如果你计划在 ROCm 上安装 PyTorch Geometric，首先需要确保你的 CUDA 环境已正确配置，尽管 ROCm 主要用于支持 AMD GPU，但在一些兼容模式下，CUDA 仍然有用。

5.1.1 检查 PyTorch 是否支持 CUDA

首先，你需要确认你的 PyTorch 是否已经安装并启用了 CUDA 支持：

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

输出结果应为 True，如果为 False，说明 CUDA 支持未正确安装，需要进行调试。

5.1.2 设置 CUDA 环境变量

在安装前，确保 CUDA 环境正确设置。需要将 CUDA 的路径添加到系统的环境变量中，确保安装过程能正确找到相关的库和工具。

假设 CUDA 安装路径为 /usr/local/cuda，则可以通过以下命令设置环境变量：

export PATH=/usr/local/cuda/bin:$PATH
echo $PATH
# 输出应包含 /usr/local/cuda/bin
>>> /usr/local/cuda/bin:...

接着，设置 CPATH 环境变量：

export CPATH=/usr/local/cuda/include:$CPATH
echo $CPATH
# 输出应包含 /usr/local/cuda/include
>>> /usr/local/cuda/include:...

如果你使用的是 Linux 系统，还需要将 CUDA 的共享库路径添加到 LD_LIBRARY_PATH 中：

export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
echo $LD_LIBRARY_PATH
# 输出应包含 /usr/local/cuda/lib64
>>> /usr/local/cuda/lib64:...

对于 macOS 用户，则应将路径添加到 DYLD_LIBRARY_PATH：

export DYLD_LIBRARY_PATH=/usr/local/cuda/lib:$DYLD_LIBRARY_PATH
echo $DYLD_LIBRARY_PATH
# 输出应包含 /usr/local/cuda/lib
>>> /usr/local/cuda/lib:...

5.1.3 验证 nvcc 是否可用

nvcc 是 NVIDIA CUDA 编译器，你可以通过以下命令检查是否能从终端访问 nvcc：

nvcc --version
# 输出应该显示当前安装的 CUDA 版本，例如：
# nvcc: NVIDIA (R) Cuda compiler driver
# Cuda compilation tools, release 11.8, V11.8.89
>>> 11.8

确保PyTorch并且系统 CUDA 版本匹配：

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

5.2 安装 PyTorch Geometric 所需软件包

安装 PyTorch Geometric 及其依赖的扩展包。以下命令会安装 PyTorch Geometric 所需的各个子包，包括 torch-scatter, torch-sparse, torch-cluster 等。

pip install --verbose git+https://github.com/pyg-team/pyg-lib.git
pip install --verbose torch_scatter
pip install --verbose torch_sparse
pip install --verbose torch_cluster
pip install --verbose torch_spline_conv

这些命令会下载并编译各个依赖库，确保你能够顺利使用 PyTorch Geometric。

5.3 强制重新安装和调试

在极少数情况下，CUDA 或 Python 路径问题可能会导致安装失败。pip甚至可能表示安装成功，但执行会崩溃。我们在常见问题解答小节中收集了常见的安装错误。如果常见问题解答无法帮助您解决问题，请创建问题。在此之前，请按照官方安装指南验证您的 CUDA 是否已正确设置。
你可以尝试强制重新安装相关软件包，以避免由于缓存问题导致的错误：

pip --force-reinstall --no-cache-dir
pip --verbose

通过设置 --verbose 参数，你可以查看详细的安装日志，以帮助诊断安装过程中的问题。

六、常见安装问题及解决方案

6.1 出现 “undefined symbol: make_function_schema” 错误

如果你遇到如下错误：

undefined symbol: make_function_schema

通常原因如下：

1. 安装的 PyTorch 版本与 ${TORCH} 包指定的版本不匹配。
2. 安装的 CUDA 版本与 PyTorch 所使用的 CUDA 版本不一致。

解决方案：

1. 检查 PyTorch 版本

确认你安装的 PyTorch 版本及其支持的 CUDA 版本：

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

输出示例：

1.13.0

接着，检查 PyTorch 支持的 CUDA 版本：

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

输出示例：

11.8

2. 检查 CUDA 版本

使用以下命令检查系统中安装的 CUDA 版本：

nvcc --version

输出示例：

nvcc: NVIDIA (R) Cuda compiler driver
Cuda compilation tools, release 11.8, V11.8.89

确保 PyTorch 版本的 CUDA 与系统安装的 CUDA 版本一致。

3. 重新安装并清除缓存

若发现版本不匹配，强制重新安装 PyTorch 及相关依赖，并清除缓存：

pip install --force-reinstall --no-cache-dir torch
pip install --force-reinstall --no-cache-dir torch_scatter torch_sparse torch_cluster

若仍然存在问题，可以尝试从源代码重新安装相关扩展包：

pip install --force-reinstall --no-cache-dir
pip install --verbose

6.2 安装时出现 “ModuleNotFoundError” 错误

遇到 ModuleNotFoundError 错误时，通常是由于 PyG 的依赖库没有正确安装。可以尝试重新安装必要的依赖库：

pip install torch-scatter torch-sparse torch-cluster torch-spline-conv

6.3 CUDA 版本不匹配

如果出现以下错误：

• CUDA version mismatch：表示 PyTorch 或 PyTorch Geometric 版本与 CUDA 版本不兼容。
• No module named 'torch_scatter' 或类似错误：可能是安装了不兼容的版本。

解决方案：

• 确保安装了与系统 CUDA 版本兼容的 cudatoolkit。
• 使用的 PyTorch 和 PyTorch Geometric 版本与 CUDA 版本必须匹配。

6.4 如何确认安装成功？

安装完 PyG 后，运行以下代码验证安装是否成功：

import torch
import torch_geometric
print(torch.__version__)
print(torch_geometric.__version__)

如果没有报错，且版本号正确，则说明安装成功。

6.5 如何调整 CUDA 版本？

如果你的系统 CUDA 版本与当前版本不匹配，你可以选择不同版本的 CUDA 进行安装。例如，若要使用 CUDA 11.6，可以按如下方式安装：

conda install pytorch=1.13 torchvision torchaudio cudatoolkit=11.6 -c pytorch
conda install pyg=*=*cu116 -c pyg

这样，你可以根据自己的硬件和软件环境选择合适的 CUDA 版本进行安装。

七、安装流程图示

为了帮助更直观地理解整个安装流程，以下是 PyTorch Geometric 安装的简化流程图：

该流程图展示了从安装 PyTorch 到解决常见问题的整个过程，帮助用户理解每个步骤的关系。

总结

安装 PyTorch Geometric（PyG）并不复杂，但需要根据不同的环境和需求选择适合的安装方法。通过 Conda 或 PyPi 安装是最为常见且简便的方式，适合大多数用户。而对于需要更多定制或特定版本的用户，直接从源代码安装或通过 Wheels 安装也是不错的选择。无论你采用何种方式，确保 CUDA 环境正确配置以及安装所需的依赖包，都是顺利安装 PyG 的关键。

在安装过程中，用户可能会遇到一些常见的错误，例如 “undefined symbol: make_function_schema” 或 “ModuleNotFoundError” 错误。本文提供了详细的故障排查和解决方案，帮助你快速识别并解决这些问题。最终，随着正确安装和配置，你可以开始使用 PyTorch Geometric，进行高效的图神经网络建模和实验，推动你的项目和研究向前发展。

通过本文的指导，你应该能根据自己的环境需求选择最合适的安装方式，并确保 PyTorch Geometric 在你的机器上成功运行，开始图数据分析的探索旅程。

---