安装指南

一、安装前的准备

1.1 确认 Python 版本

PyTorch 当前稳定版（2.7.0）要求 Python 版本在 3.10 ~ 3.14 之间。请先确认你的 Python 版本：

python --version                            # 查看 Python 版本，需要 3.10 及以上

如果你的 Python 版本低于 3.10，请先升级 Python。

---

1.2 确认操作系统

操作系统	最低版本要求	备注
Windows	Windows 7 及以上	推荐 Windows 10/11
Linux	glibc >= 2.28	Ubuntu 20.04+、CentOS 8+、Debian 10+ 等
macOS	macOS 10.15 (Catalina) 及以上	仅支持 CPU 版本，不支持 CUDA

---

1.3 确认是否拥有 NVIDIA GPU

安装 GPU 版本前，必须先确认你的电脑是否有 NVIDIA 显卡：

# Windows：在命令提示符或 PowerShell 中执行
nvidia-smi                                 # 查看显卡信息和驱动版本

# Linux：在终端中执行
nvidia-smi                                 # 查看显卡信息和驱动版本

• 如果命令成功输出显卡信息，说明你有 NVIDIA GPU，可以考虑安装 GPU 版本
• 如果提示"命令未找到"，说明没有安装 NVIDIA 驱动或没有 NVIDIA GPU，请安装 CPU 版本

macOS 用户注意： macOS 不支持 CUDA，只能安装 CPU 版本，无需执行此步骤。

---

二、CPU 版本 vs GPU 版本

2.1 如何选择

场景	推荐版本	原因
没有 NVIDIA GPU	CPU 版本	无法使用 CUDA 加速
有 NVIDIA GPU 但驱动较旧	CPU 版本或升级驱动	GPU 版本对驱动有最低要求
有 NVIDIA GPU 且驱动版本满足要求	GPU 版本	训练速度大幅提升
macOS 用户	CPU 版本	macOS 不支持 CUDA
仅做推理或小规模实验	CPU 版本	安装简单，无需配置 GPU
大规模训练或生产环境	GPU 版本	训练速度提升 10~50 倍

2.2 CUDA 版本与 NVIDIA 驱动的对应关系

安装 GPU 版本时，PyTorch 内置了 CUDA 运行时库，不需要你单独安装 CUDA Toolkit。但是，你的 NVIDIA 显卡驱动版本必须满足对应 CUDA 版本的最低要求。

CUDA 版本	Linux 最低驱动版本	Windows 最低驱动版本
CUDA 11.8	>= 520.61.05	>= 520.06
CUDA 12.6	>= 560.28.03	>= 560.76
CUDA 12.8	>= 570.26	>= 570.65

重要提示： NVIDIA 驱动是向下兼容的，即新版本的驱动支持旧版本的 CUDA。如果你的驱动版本高于上表中的最低要求，你可以选择任意 CUDA 版本的 PyTorch。

2.3 如何选择 CUDA 版本

情况	推荐 CUDA 版本
驱动版本 >= 570	CUDA 12.8（最新，推荐）
驱动版本 >= 560 且 < 570	CUDA 12.6
驱动版本 >= 520 且 < 560	CUDA 11.8
驱动版本 < 520	需先升级驱动，或使用 CPU 版本

查看驱动版本的方法：

nvidia-smi                                 # 右上角显示 Driver Version

---

三、torch、torchvision、torchaudio 版本对应关系

PyTorch 生态中的三个核心库必须版本匹配才能正常工作。下表列出了常用版本的对应关系：

torch	torchvision	torchaudio	Python 版本
2.7.0	0.22.0	2.7.0	>= 3.9, <= 3.13
2.6.0	0.21.0	2.6.0	>= 3.9, <= 3.13
2.5.1	0.20.1	2.5.1	>= 3.9, <= 3.12
2.5.0	0.20.0	2.5.0	>= 3.9, <= 3.12
2.4.1	0.19.1	2.4.1	>= 3.9, <= 3.12
2.4.0	0.19.0	2.4.0	>= 3.9, <= 3.12
2.3.1	0.18.1	2.3.1	>= 3.9, <= 3.12
2.3.0	0.18.0	2.3.0	>= 3.9, <= 3.12
2.2.2	0.17.2	2.2.2	>= 3.8, <= 3.11
2.2.1	0.17.1	2.2.1	>= 3.8, <= 3.11
2.1.2	0.16.2	2.1.2	>= 3.8, <= 3.11
2.0.1	0.15.2	2.0.2	>= 3.8, <= 3.11

注意： 安装时必须确保三个包的版本在同一行中，否则可能出现不兼容问题。本文以下安装命令均基于当前稳定版 torch==2.7.0 编写。

---

四、使用 pip 安装（推荐）

以下命令均使用清华镜像源加速下载。

4.1 CPU 版本（Windows / Linux / macOS）

CPU 版本的 PyTorch 包在标准 PyPI 上发布，可以直接使用清华镜像源安装：

pip3 install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 --index-url https://pypi.tuna.tsinghua.edu.cn/simple   # 使用清华镜像源安装 CPU 版本

---

4.2 GPU 版本 — CUDA 12.8（Windows / Linux）

GPU 版本的 PyTorch 包（带 +cu128 后缀）托管在 PyTorch 官方服务器上，不在标准 PyPI 中，因此清华镜像源无法直接提供。正确做法是：PyTorch CUDA 包从官方源下载，其他依赖包从清华镜像源下载：

pip3 install torch==2.7.0+cu128 torchvision==0.22.0+cu128 torchaudio==2.7.0+cu128 --index-url https://download.pytorch.org/whl/cu128 --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple   # GPU 版本：PyTorch CUDA 包走官方源，其他依赖走清华镜像源

说明： --index-url 指定主下载源（PyTorch CUDA 包），--extra-index-url 指定备用源（清华镜像，用于下载 numpy 等依赖包）。如果你的 NVIDIA 驱动版本低于 570，请先升级驱动，或参考第三章版本对应表改用其他 CUDA 版本的安装命令。

---

4.3 macOS 安装

macOS 仅支持 CPU 版本：

pip3 install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 --index-url https://pypi.tuna.tsinghua.edu.cn/simple   # macOS 使用清华镜像源安装 CPU 版本

---

五、使用 Conda 安装

如果你使用 Anaconda 或 Miniconda 管理 Python 环境，也可以通过 conda 安装 PyTorch。

5.1 创建独立的虚拟环境（推荐）

conda create -n pytorch_env python=3.13     # 创建名为 pytorch_env 的虚拟环境，指定 Python 3.13
conda activate pytorch_env                  # 激活虚拟环境

5.2 安装命令

CPU 版本

conda install pytorch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 cpuonly -c pytorch   # 安装 CPU 版本

GPU 版本 — CUDA 12.8

conda install pytorch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 pytorch-cuda=12.8 -c pytorch -c nvidia   # 安装 CUDA 12.8 版本

---

六、验证安装是否成功

6.1 基本验证

安装完成后，运行以下代码确认 PyTorch 是否安装成功：

import torch                               # 导入 PyTorch 库
print(torch.__version__)                   # 打印 PyTorch 版本号

如果输出了版本号（如 2.7.0），说明安装成功。

---

6.2 验证 GPU 是否可用

import torch                               # 导入 PyTorch 库
print(torch.cuda.is_available())           # 检查 CUDA 是否可用，返回 True 或 False
print(torch.cuda.get_device_name(0))       # 如果可用，打印 GPU 设备名称

• 如果 torch.cuda.is_available() 返回 True，说明 GPU 版本安装正确，可以使用 GPU 加速
• 如果返回 False，可能是驱动版本不匹配或安装了 CPU 版本

---

6.3 简单张量运算测试

import torch                               # 导入 PyTorch 库

# 测试 CPU 运算
x = torch.rand(5, 3)                       # 在 CPU 上创建一个 5x3 的随机张量
print("CPU 张量：")                         # 打印提示
print(x)                                   # 打印张量内容

# 测试 GPU 运算（仅 GPU 版本可用）
if torch.cuda.is_available():              # 检查 GPU 是否可用
    x_gpu = x.to("cuda")                   # 将张量移动到 GPU
    y_gpu = torch.rand(5, 3, device="cuda") # 直接在 GPU 上创建随机张量
    z_gpu = x_gpu + y_gpu                  # 在 GPU 上执行加法运算
    print("GPU 张量运算结果：")              # 打印提示
    print(z_gpu)                           # 打印运算结果
    print("GPU 运算测试通过！")              # 打印成功提示
else:
    print("GPU 不可用，仅 CPU 可用")          # 提示 GPU 不可用

---

七、常见问题与解决方案

Q1：安装后 torch.cuda.is_available() 返回 False 怎么办？

请按以下步骤排查：

# 第 1 步：确认你安装的是 GPU 版本
pip3 show torch                            # 查看 torch 包信息，确认版本号中是否包含 +cu128

# 第 2 步：确认 NVIDIA 驱动是否正常
nvidia-smi                                 # 查看驱动版本和 GPU 信息

# 第 3 步：确认驱动版本是否满足 CUDA 版本的最低要求
# 参考本文"2.2 CUDA 版本与 NVIDIA 驱动的对应关系"

常见原因：

1. 安装了 CPU 版本 — 重新安装时使用 GPU 版本的安装命令
2. NVIDIA 驱动版本过低 — 更新驱动到最新版本
3. 没有 NVIDIA GPU — 只能使用 CPU 版本

---

Q2：如何卸载并重新安装？

pip3 uninstall torch torchvision torchaudio -y   # 卸载已安装的 PyTorch 相关包
# 然后按照本文的安装命令重新安装

---

Q3：如何在虚拟环境中安装？

推荐使用虚拟环境隔离项目依赖：

# 方法 1：使用 Python 自带的 venv
python -m venv pytorch_env                 # 创建虚拟环境
pytorch_env\Scripts\activate               # Windows 激活虚拟环境
# source pytorch_env/bin/activate          # Linux/macOS 激活虚拟环境

# 方法 2：使用 Conda
conda create -n pytorch_env python=3.13    # 创建 Conda 虚拟环境
conda activate pytorch_env                 # 激活虚拟环境

激活虚拟环境后，再按照本文的安装命令进行安装即可。

---

Q4：如何安装历史版本的 PyTorch？

如果你需要安装旧版本的 PyTorch，请先查阅第三章的版本对应表，确保三个包的版本号匹配。以 torch 2.6.0 为例：

# CPU 版本
pip3 install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://pypi.tuna.tsinghua.edu.cn/simple   # 安装历史版本 CPU 版本

# GPU 版本（CUDA 12.8）
pip3 install torch==2.6.0+cu128 torchvision==0.21.0+cu128 torchaudio==2.6.0+cu128 --index-url https://download.pytorch.org/whl/cu128 --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple   # 安装历史版本 GPU 版本

注意： 并非所有历史版本都支持 CUDA 12.8。旧版本 PyTorch 可能仅支持 CUDA 11.8 或 12.1 等，请参考 PyTorch 官网历史版本页面确认可用的 CUDA 版本。

---

Q5：清华镜像源安装 GPU 版本报错怎么办？

清华镜像源中不包含带 CUDA 支持的 PyTorch 包（如 torch-2.7.0+cu128），因此以下命令会失败：

# 错误示例：清华镜像源找不到 +cu128 版本的包
pip3 install torch==2.7.0+cu128 torchvision==0.22.0+cu128 torchaudio==2.7.0+cu128 --index-url https://pypi.tuna.tsinghua.edu.cn/simple

正确的做法是使用本文第四章中的命令，将 --index-url 设为 PyTorch 官方 CUDA 源，--extra-index-url 设为清华镜像源。

---

Q6：如何确认已安装的 torch、torchvision、torchaudio 版本是否匹配？

import torch                               # 导入 PyTorch 库
import torchvision                         # 导入 torchvision 库
import torchaudio                          # 导入 torchaudio 库

print(f"torch: {torch.__version__}")       # 打印 torch 版本号
print(f"torchvision: {torchvision.__version__}")  # 打印 torchvision 版本号
print(f"torchaudio: {torchaudio.__version__}")     # 打印 torchaudio 版本号

对照第三章的版本对应表，确认三个版本号在同一行中即可。