pytorch/pytorch

来源：https://github.com/pytorch/pytorch

PyTorch 是一个 Python 包，提供两个高级特性：

• 张量计算（类似 NumPy），支持强大的 GPU 加速
• 基于磁带（tape）的自动微分系统构建的深度神经网络

你可以在需要时重用你最喜欢的 Python 包，如 NumPy、SciPy 和 Cython 来扩展 PyTorch。

我们的主干健康（持续集成信号）可在 hud.pytorch.org（https://hud.pytorch.org/ci/pytorch/pytorch/main）查看。

• 更多关于 PyTorch
• GPU 就绪的张量库
• 动态神经网络：基于磁带的自动微分
• Python 优先
• 命令式体验
• 快速且精简
• 无痛扩展
• 安装
  • 二进制包
  • NVIDIA Jetson 平台
  • 从源码编译
    • 前置条件
    • NVIDIA CUDA 支持
    • AMD ROCm 支持
    • Intel GPU 支持
    • 获取 PyTorch 源码
    • 安装依赖
    • 安装 PyTorch
    • 调整构建选项（可选）
• Docker 镜像
  • 使用预构建镜像
  • 自行构建镜像
• 构建文档
  • 排查 CI 错误
  • 构建 PDF
• 历史版本
• 入门指南
• 资源
• 交流沟通
• 发布与贡献
• 团队
• 许可证

更多关于 PyTorch

学习 PyTorch 基础（https://pytorch.org/tutorials/beginner/basics/intro.html）

从细致层面看，PyTorch 是一个由以下组件组成的库：

通常，PyTorch 用于：

• 作为 NumPy 的替代品，利用 GPU 的性能。
• 作为深度学习研究平台，提供最大的灵活性和速度。

进一步阐述：

GPU 就绪的张量库

如果你使用 NumPy，那么你已经使用过张量（即 ndarray）。
张量示意图
PyTorch 提供可以驻留在 CPU 或 GPU 上的张量，并大幅加速计算。
我们提供丰富的张量例程来加速并满足你的科学计算需求，例如切片、索引、数学运算、线性代数、归约等。而且它们速度很快！

动态神经网络：基于磁带的自动微分

PyTorch 有一种独特的构建神经网络的方式：使用并重放磁带记录器。
大多数框架如 TensorFlow、Theano、Caffe 和 CNTK 都采用静态世界观。你必须构建一个神经网络并反复重用同一结构。改变网络行为意味着必须从头开始。
在 PyTorch 中，我们使用一种称为反向模式自动微分的技巧，它允许你任意改变网络的行为，且无延迟或开销。
我们的灵感来源于多项研究论文，以及当前和过去的工作，如 torch-autograd（https://github.com/twitter/torch-autograd）、autograd（https://github.com/HIPS/autograd）、Chainer（https://chainer.org）等。
虽然这种技巧并非 PyTorch 独有，但它是迄今为止最快的实现之一。你可以在疯狂的研究中获得速度和灵活性的最佳结合。
动态图

Python 优先

PyTorch 并不是一个将 Python 绑定到单一 C++ 框架上的库。它被设计为与 Python 深度集成。
你可以像使用 NumPy（https://www.numpy.org/）/ SciPy（https://www.scipy.org/）/ scikit-learn（https://scikit-learn.org）等一样自然地使用它。
你可以直接用 Python 编写新的神经网络层，使用你喜欢的库，并使用 Cython（https://cython.org/）和 Numba（http://numba.pydata.org/）等包。
我们的目标是在适当的地方不重复造轮子。

命令式体验

PyTorch 被设计为直观、线性思维且易于使用。当你执行一行代码时，它就会被执行。没有异步世界观。
当你进入调试器或收到错误消息和堆栈跟踪时，理解它们非常直接。堆栈跟踪精确指向你代码定义的位置。
我们希望你再也不会因为糟糕的堆栈跟踪或异步且不透明的执行引擎而花费数小时调试代码。

快速且精简

PyTorch 具有最小的框架开销。我们集成了加速库，如 Intel MKL（https://software.intel.com/mkl）和 NVIDIA（cuDNN（https://developer.nvidia.com/cudnn），NCCL（https://developer.nvidia.com/nccl））以最大化速度。
核心部分，其 CPU 和 GPU 张量及神经网络后端已经成熟并经过多年测试。
因此，无论运行小型还是大型神经网络，PyTorch 都非常快。
与 Torch 或其他替代方案相比，PyTorch 的内存使用极其高效。我们为 GPU 编写了自定义内存分配器，以确保你的深度学习模型在内存上最高效。这使你能够训练比以往更大的深度学习模型。

无痛扩展

编写新的神经网络模块或与 PyTorch 的张量 API 交互被设计为直接且抽象最少。
你可以使用 torch API 或你基于 NumPy 的库（如 SciPy）（https://pytorch.org/tutorials/advanced/numpy_extensions_tutorial.html）在 Python 中编写新的神经网络层。
如果你想用 C/C++ 编写层，我们提供了一个方便的扩展 API，高效且样板代码极少。无需编写包装代码。
你可以在这里查看教程（https://pytorch.org/tutorials/advanced/cpp_extension.html），并在这里查看示例（https://github.com/pytorch/extension-cpp）。

安装

二进制包

通过 Conda 或 pip wheel 安装二进制包的命令在我们的网站上：https://pytorch.org/get-started/locally/

NVIDIA Jetson 平台

适用于 NVIDIA Jetson Nano、Jetson TX1/TX2、Jetson Xavier NX/AGX 和 Jetson AGX Orin 的 Python wheel 在此提供（https://forums.developer.nvidia.com/t/pytorch-for-jetson-version-1-10-now-available/72048），L4T 容器在此发布（https://catalog.ngc.nvidia.com/orgs/nvidia/containers/l4t-pytorch）。
他们需要 JetPack 4.2 及以上版本，由 @dusty-nv（https://github.com/dusty-nv）和 @ptrblck（https://github.com/ptrblck）维护。

从源码编译

前置条件

如果你从源码安装，你需要：

• Python 3.10 或更高版本
• 完全支持 C++20 的编译器，如 clang 或 gcc（Linux 上需要 gcc 11.3.0 或更新）
• Visual Studio 或 Visual Studio 生成工具（仅 Windows）
• 至少 10 GB 的可用磁盘空间
• 初始构建需要 30-60 分钟（后续重新构建更快）

* PyTorch CI 使用 Visual C++ BuildTools，这些工具随 Visual Studio Enterprise、Professional 或 Community 版本提供。你也可以从 https://visualstudio.microsoft.com/visual-cpp-build-tools/ 安装生成工具。生成工具 不 随 Visual Studio Code 默认提供。

环境设置示例如下：

• Linux：
  bash $ source /bin/activate $ conda create -y -n $ conda activate

• Windows：
  bash $ source \Scripts\activate.bat $ conda create -y -n $ conda activate $ call "C:\Program Files\Microsoft Visual Studio\\Community\VC\Auxiliary\Build\vcvarsall.bat" x64

不强制要求 conda 环境。你也可以在标准虚拟环境（例如使用 uv 等工具创建）中执行 PyTorch 构建，前提是你的系统已安装所有必要的、pip 包无法获得的依赖（例如 CUDA、MKL）。

NVIDIA CUDA 支持

如果你想使用 CUDA 支持进行编译，请从我们的支持矩阵（https://pytorch.org/get-started/locally/）中选择一个受支持的 CUDA 版本，然后安装以下内容：

• NVIDIA CUDA（https://developer.nvidia.com/cuda-downloads）
• NVIDIA cuDNN（https://developer.nvidia.com/cudnn）v9.0 或更高版本
• 与 CUDA 兼容的编译器（https://gist.github.com/ax3l/9489132）

注意：你可以参考 cuDNN 支持矩阵（https://docs.nvidia.com/deeplearning/cudnn/backend/latest/reference/support-matrix.html）了解与各种受支持 CUDA、CUDA 驱动程序和 NVIDIA 硬件对应的 cuDNN 版本。

如果要禁用 CUDA 支持，请导出环境变量 USE_CUDA=0。其他可能有用的环境变量可在 setup.py 中找到。

如果 CUDA 安装在非标准位置，设置 PATH 以便能找到所需的 nvcc（例如 export PATH=/usr/local/cuda-12.8/bin:$PATH）。

如果你是为 NVIDIA Jetson 平台（Jetson Nano、TX1、TX2、AGX Xavier）构建，适用于 Jetson Nano 的 PyTorch 安装说明可在此处找到（https://devtalk.nvidia.com/default/topic/1049071/jetson-nano/pytorch-for-jetson-nano/）。

AMD ROCm 支持

如果你想使用 ROCm 支持进行编译，请安装

• AMD ROCm（https://rocm.docs.amd.com/en/latest/deploy/linux/quick_start.html）4.0 及以上版本安装
• ROCm 目前仅支持 Linux 系统。

默认情况下，构建系统期望 ROCm 安装在 /opt/rocm。如果 ROCm 安装在不同目录，必须设置 ROCM_PATH 环境变量指向 ROCm 安装目录。
构建系统会自动检测 AMD GPU 架构。可选地，可以通过环境变量 PYTORCH_ROCM_ARCH 显式设置 AMD GPU 架构。
AMD GPU 架构（https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html#supported-gpus）

如果要禁用 ROCm 支持，请导出环境变量 USE_ROCM=0。其他可能有用的环境变量可在 setup.py 中找到。

Intel GPU 支持

如果你想使用 Intel GPU 支持进行编译，请按照以下步骤操作：

• PyTorch Intel GPU 前置条件（https://www.intel.com/content/www/us/en/developer/articles/tool/pytorch-prerequisites-for-intel-gpu.html）说明。
• Intel GPU 支持 Linux 和 Windows。

如果要禁用 Intel GPU 支持，请导出环境变量 USE_XPU=0。其他可能有用的环境变量可在 setup.py 中找到。

获取 PyTorch 源码

``bash
git clone https://github.com/pytorch/pytorch
cd pytorch

如果正在更新现有检出

git submodule sync
git submodule update –init –recursive
``

安装依赖

通用
``bash

在克隆源码后，从 PyTorch 目录运行此命令（使用上述“获取 PyTorch 源码”部分）

pip install –group dev
``

在 Linux 上
``bash
pip install mkl-static mkl-include

仅 CUDA：如果需要，为 GPU 添加 LAPACK 支持

magma 安装：在激活的 conda 环境中运行。指定要安装的 CUDA 版本

.ci/docker/common/install_magma_conda.sh 12.4

（可选）如果使用 torch.compile 配合 inductor/triton，安装匹配版本的 triton

在克隆后从 pytorch 目录运行

对于 Intel GPU 支持，请先在运行命令前显式 export USE_XPU=1

make triton
``

在 Windows 上
``bash
pip install mkl-static mkl-include

如果需要 torch.distributed，添加这些包。

Windows 上的分布式包支持是原型功能，可能会发生变化。

conda install -c conda-forge libuv=1.51
``

安装 PyTorch

在 Linux 上
如果你正在为 AMD ROCm 编译，请先运行此命令：
``bash

仅当你为 ROCm 编译时运行此命令

python tools/amd_build/build_amd.py
``

安装 PyTorch
``bash

conda 环境的 CMake 前缀

export CMAKE_PREFIX_PATH=“{CONDA_PREFIX:-'$(dirname $(which conda))/../'}:{CMAKE_PREFIX_PATH}”
python -m pip install –no-build-isolation -v -e .

非 conda 环境（例如 Python venv）的 CMake 前缀

在激活 venv 后调用以下命令

export CMAKE_PREFIX_PATH=“{VIRTUAL_ENV}:{CMAKE_PREFIX_PATH}”
``

在 macOS 上
bash python -m pip install --no-build-isolation -v -e .

在 Windows 上
如果要构建旧版 Python 代码，请参考 Building on legacy code and CUDA（https://github.com/pytorch/pytorch/blob/main/CONTRIBUTING.md#building-on-legacy-code-and-cuda）

纯 CPU 构建
在此模式下，PyTorch 计算将在 CPU 上运行，而不是 GPU。
cmd python -m pip install --no-build-isolation -v -e .

关于 OpenMP 的说明：所需的 OpenMP 实现是 Intel OpenMP（iomp）。为了链接 iomp，你需要手动下载该库，并通过调整 CMAKE_INCLUDE_PATH 和 LIB 来设置构建环境。此处的说明（https://github.com/pytorch/pytorch/blob/main/docs/source/notes/windows.rst#building-from-source）是设置 MKL 和 Intel OpenMP 的示例。如果没有这些 CMake 配置，将使用 Microsoft Visual C OpenMP 运行时（vcomp）。

基于 CUDA 的构建
在此模式下，PyTorch 计算将通过 CUDA 利用 GPU 进行更快的数值运算。
构建带有 CUDA 的 PyTorch 需要 NVTX（https://docs.nvidia.com/gameworks/content/gameworkslibrary/nvtx/nvidia_tools_extension_library_nvtx.htm）。NVTX 是 CUDA 发行版的一部分，在其中被称为“Nsight Compute”。要将它安装到已安装的 CUDA 上，请再次运行 CUDA 安装并勾选相应复选框。确保在 Visual Studio 之后安装带有 Nsight Compute 的 CUDA。
目前，VS 2017 / 2019 和 Ninja 作为 CMake 的生成器受支持。如果在 PATH 中检测到 ninja.exe，则 Ninja 将被用作默认生成器，否则将使用 VS 2017 / 2019。如果选择 Ninja 作为生成器，则会选择最新的 MSVC 作为底层工具链。
通常还需要附加库，如 Magma（https://developer.nvidia.com/magma）、oneDNN（又名 MKLDNN 或 DNNL）（https://github.com/oneapi-src/oneDNN）和 Sccache（https://github.com/mozilla/sccache）。请参考 installation-helper（https://github.com/pytorch/pytorch/tree/main/.ci/pytorch/win-test-helpers/installation-helpers）进行安装。
你可以参考 build_pytorch.bat（https://github.com/pytorch/pytorch/blob/main/.ci/pytorch/win-test-helpers/build_pytorch.bat）脚本来查看其他一些环境变量的配置。

``cmd
cmd :: 在下载并解压 mkl 包后设置环境变量，
:: 否则 CMake 会抛出错误，如 Could NOT find OpenMP。
set CMAKE_INCLUDE_PATH={Your directory}\mkl\include
set LIB={Your directory}\mkl\lib;%LIB%

:: 在继续之前，请仔细阅读上一节的内容。