WSL2 (Ubuntu)环境下通过镜像源安装 CUDA 版 PyTorch 的完全避坑指南(2026年4月)

EachYoungX
8 阅读6分钟

发布时间：2026年4月

如果 GPU、PyTorch、NumPy 都进入了新的稳定阶段，该方法可能会失效

文章内容已经过实际测试有效，如果你在实际情况中发现了已知问题，请检查时间和版本并仔细阅读常见问题部分

一、目的与背景

本文目的： 明确、严谨地指导如何在 WSL (Windows Subsystem for Linux) 环境中，通过国内镜像源，使用 Conda 一次性正确安装带有 CUDA 支持的 PyTorch 版本。

背景说明：
在深度学习开发中，由于 Linux 环境在文件 I/O、内存管理及生态兼容性上的优势，许多开发者选择从 Windows 迁移到 WSL。迁移后，原有的 Anaconda/Miniconda 环境无法直接平移，必须在 WSL 内重新下载 Miniconda 并配置环境。直接使用镜像源容易下到CPU版，而由于网络隔离和依赖冲突，直接照搬官方命令极易导致底层 C 库崩溃，以及代理配置复杂、版本依赖冲突等各种情况发生。本文旨在系统性解决这些问题。

二、安装步骤

1. 网络与代理配置

在 WSL 中，由于宿主机代理软件的设置差异，Conda 极易因代理问题报 HTTP 000 CONNECTION FAILED。安装前必须确保环境纯净。

第一步：彻底清除所有残留代理

# 清除当前 Shell 的环境变量代理
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
# 清除 Conda 配置文件中可能存在的代理设置
conda config --remove-key proxy_servers.http 2>/dev/null
conda config --remove-key proxy_servers.https 2>/dev/null

第二步：验证代理已清空

# 确认 Shell 环境变量无代理
env | grep -i proxy
# 确认 Conda 配置无代理
conda config --show | grep proxy

（以上两个命令均应无任何输出，方可进行下一步）

第三步：按需添加代理设置（可选，但不建议）
如果你的 WSL 必须通过宿主机代理才能访问外网，请在此处显式添加，避免 Conda 抓取系统乱码环境变量：

# 将端口号替换为你宿主机代理软件实际监听的端口（如 Clash 默认 7890）
conda config --set proxy_servers.http http://127.0.0.1:7890
conda config --set proxy_servers.https http://127.0.0.1:7890

添加后，再次执行第二步的验证命令，应能看到刚配置的明确代理地址。

2. 清理现有 Conda 镜像源（避免重复或冲突）

为了确保后续添加的镜像源是干净且唯一的，避免因为以前残留的 custom_channels、default_channels 等配置导致包混源或通道优先级混乱，需要先清理已有镜像源配置：

# 删除 custom_channels 中的所有自定义镜像
conda config --remove-key custom_channels 2>/dev/null
# 删除可能存在的自定义 default_channels
conda config --remove-key default_channels 2>/dev/null
# 彻底清空 channels 列表（保留 defaults 是安全的，但为避免干扰也建议清空）
conda config --remove-key channels 2>/dev/null

执行后可用 conda config --show 检查对应项是否已消失。

3. 配置 Conda 镜像源（以清华镜像源为例）

为了防止下载中断并避免默认源与 PyTorch 源发生包版本冲突，需严格配置 .condarc 文件。

cat > ~/.condarc << 'EOF'
channels:
  - defaults
show_channel_urls: true
default_channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
custom_channels:
  conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
channel_priority: strict
EOF
# 清除索引缓存使配置生效
conda clean -i

4. 检查本地 CUDA 版本

在 WSL 中，nvidia-smi 显示的是宿主机的 NVIDIA 驱动版本及该驱动支持的最高 CUDA 版本。

nvidia-smi

注：右上角的 CUDA Version 指的是驱动支持上限，并非你实际安装的 CUDA Toolkit 版本。在使用 Conda 安装 PyTorch 时，无需提前在 WSL 里安装 CUDA Toolkit，只需指定小于等于该上限的版本即可。

5. 创建环境与安装（以 RTX 4060 Laptop, CUDA 12.4 为例）

# 创建独立的 Python 3.10 环境
conda create -n care_env python=3.10 -y
conda activate care_env

# 执行核心安装命令
conda install -y -c pytorch \
    pytorch torchvision torchaudio pytorch-cuda=12.4 \
    "intel-openmp<2025"

命令原理解释：

  • -c pytorch：强制追加 PyTorch 官方通道（会自动映射到前面配置的清华 pytorch 镜像）。
  • pytorch-cuda=12.4：指定 PyTorch 所捆绑的 CUDA 运行时版本为 12.4。
  • "intel-openmp<2025"：关键约束（原因见后文常见问题）。

6. 最终验证

执行以下 Python 单行命令，必须严格满足四个 True/具体数值输出：

python3 -c "
import torch
print('PyTorch:', torch.__version__)
print('CUDA available:', torch.cuda.is_available())
print('CUDA version:', torch.version.cuda)
if torch.cuda.is_available():
    print('cuDNN:', torch.backends.cudnn.version())
    print('GPU:', torch.cuda.get_device_name(0))
else:
    print('CUDA 不可用')
"

预期输出示例：

PyTorch: 2.5.1
CUDA available: True
CUDA version: 12.4
cuDNN: 90100
GPU: NVIDIA GeForce RTX 4060 Laptop GPU

三、常见问题与底层原理分析（FAQ）

Q1：安装报错 libmkl_rt.so.2: cannot open shared object file 导致 NumPy/PyTorch 崩溃，怎么办？

解决策略： 这是因为卸载或更新某个库时，破坏了 MKL（数学核心库）的依赖树。

  • 何时只需重装库： 如果仅仅是 import numpy 报错，可以尝试 conda install -y mkl mkl-service numpy。
  • 何时必须重建环境： 如果在重装过程中，发现 Conda 开始把 pytorch=2.5.1 降级为 pytorch=2.10.0，或者把 cuda12.4 替换为 cpu_openblas，立刻停止操作。这说明依赖树已经彻底绞死（Solve Environment 失败），此时最快、最干净的方案是 conda deactivate && conda remove -n env_name --all -y，从头来过。不要在坏掉的环境里反复 conda install，越装越烂。

Q2：为什么要加 "intel-openmp<2025" 这个约束？

原因： 在 2024 年末至 2025 年初的 Conda 包分发中，intel-openmp 更新到了 2025 版本。该版本修改了 JIT（即时编译）分析相关的符号导出，导致缺失 iJIT_NotifyEvent 符号。PyTorch 底层的 libtorch_cpu.so 在初始化时强依赖此符号，会直接抛出 ImportError: undefined symbol: iJIT_NotifyEvent。锁定 <2025 是目前最稳妥的物理隔离手段。

Q3：为什么不直接 conda install pytorch，一定要加 -c pytorch？

原因： Conda 的 defaults 默认通道中不包含 GPU 版本的 PyTorch，只有 CPU 版本。如果你不显式指定 -c pytorch，Conda 求解器会为了满足依赖，直接从 defaults 拉取纯 CPU 版本覆盖掉你的预期。即使你配了镜像，通道的优先级也必须通过 -c 显式提升。

四、未来硬件/软件更新后的自查指南

当未来你的显卡升级、PyTorch 发布大版本（如 2.6、3.0）或 NumPy 发布新版本时，如果遇到类似问题，请遵循以下自查逻辑：

  1. 核对驱动上限： 运行 nvidia-smi，确认新驱动支持的最高 CUDA 版本。
  2. 查阅官方命令： 访问 PyTorch 官网，获取对应版本的安装命令。注意提取其中的 pytorch-cuda=X.X 版本号。
  3. 测试约束解除： 在新环境中，先不加 "intel-openmp<2025" 进行安装。
    • 如果成功，说明 Intel 官方或 Conda-forge 已经修复了该符号缺失问题。
    • 如果再次出现 iJIT_NotifyEvent 相关报错，说明底层冲突仍在，请继续在安装命令末尾追加 "intel-openmp<你的报错版本减1" 的约束。
  4. NumPy 兼容性自查： 现代深度学习库对 NumPy 2.x 的支持仍在完善中。如果安装后出现 numpy.core.multiarray 报错，通常是 NumPy 版本过高，使用 conda install "numpy<2.0" 降级即可，切勿因此去重装整个 PyTorch。

若有错误请指正

avatar
文章
阅读
粉丝