《nnU-Net 0基础入门（2）：安装 nnU-Net v2，环境、PyTorch 和路径变量一次讲清》

本篇学习目标

这是《nnU-Net 0基础入门》系列的第 2 篇。上一篇我们解释了 nnU-Net v2 为什么不是“一个 U-Net 网络”，而是一整套自动配置医学图像分割 pipeline。本文开始进入实操：安装 nnU-Net v2。

读完本文，你应该能够：

理解为什么官方建议先安装 PyTorch，再安装 nnU-Net v2。
知道 nnUNet_raw、nnUNet_preprocessed、nnUNet_results 三个路径变量分别放什么。
在 Linux 上完成一个可用于后续教程的基础环境配置。
用简单命令检查 Python、PyTorch、CUDA 和 nnU-Net v2 是否可用。

1. 安装前先理解：nnU-Net v2 依赖什么

nnU-Net v2 是一个 Python 包，但它不是普通的小工具。它要完成医学图像分割训练，背后依赖 PyTorch、图像读写、预处理、多进程数据增强、GPU 训练和模型保存。因此安装时不要只记一条 pip install nnunetv2。

官方安装文档给出的关键要求可以概括为：

使用 Python 3.10 或更新版本。
Linux 是主要目标平台，Windows 和 macOS 也支持。
训练强烈建议使用 GPU。
必须先根据你的硬件安装 PyTorch，再安装 nnunetv2。
必须设置三个路径变量：nnUNet_raw、nnUNet_preprocessed、nnUNet_results。

这里的路径变量指的是环境变量。环境变量可以理解为当前系统或终端会话里的“全局配置”。nnU-Net v2 通过这三个变量知道：原始数据在哪里、预处理结果放哪里、训练好的模型放哪里。

2. 推荐安装流程总览

本文以 Linux + NVIDIA GPU 为主线。Windows 和 macOS 的路径写法略有不同，但逻辑一致。

flowchart TD
    A[创建 Python 环境] --> B[安装匹配硬件的 PyTorch]
    B --> C[验证 torch 和 CUDA]
    C --> D[安装 nnunetv2]
    D --> E[创建三个 nnU-Net 目录]
    E --> F[设置环境变量]
    F --> G[验证 nnU-Net 命令可用]

这张图里最容易出错的是第 2 步和第 6 步：PyTorch 没装对，后面训练就用不了 GPU；路径变量没设对，nnU-Net 会找不到数据和结果目录。

3. 创建一个干净的 Python 环境

强烈建议为 nnU-Net v2 单独创建环境，避免和其他项目的 PyTorch、CUDA、numpy、scipy 版本互相影响。你可以用 conda，也可以用 venv。下面给出 conda 示例：

conda create -n nnunetv2 python=3.10 -y
conda activate nnunetv2

python --version
pip --version

如果你使用 venv，可以这样做：

python3.10 -m venv ~/venvs/nnunetv2
source ~/venvs/nnunetv2/bin/activate

python --version
pip --version

这里的 python --version 至少应该显示 Python 3.10。不要在一个已经装过很多深度学习框架的旧环境里直接装 nnU-Net v2，后续排错成本会很高。

4. 先安装 PyTorch：按你的硬件选择

官方 nnU-Net 安装页明确要求：先安装适合你硬件的 PyTorch，再安装 nnunetv2。原因很简单：PyTorch 的安装包和 CUDA、ROCm、CPU 版本强相关，不能让下游包随便替你决定。

推荐做法是打开 PyTorch 官方安装页面，根据自己的系统选择：

Linux / Windows / macOS
pip 或 conda
Python
CUDA、ROCm、MPS 或 CPU

例如，在 PyTorch 官网选择器中，Linux + pip + Python + CUDA 某个版本时，会给出类似这样的命令。请以官网当前选择器为准，不要机械复制旧博客里的命令：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

如果你没有 NVIDIA GPU，只是想先学习数据格式和命令，可以安装 CPU 版本。但要注意：nnU-Net v2 的真实训练非常依赖 GPU，CPU 训练通常不适合实际项目。

安装后先验证 PyTorch：

python - <<'PY'
import torch
print("torch:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("gpu:", torch.cuda.get_device_name(0))
PY

如果你期望使用 NVIDIA GPU，但 torch.cuda.is_available() 输出 False，先不要继续安装 nnU-Net。应先检查 GPU 驱动、CUDA 版本和 PyTorch 安装命令是否匹配。

5. 安装 nnU-Net v2：普通使用与开发模式

如果你只是想使用 nnU-Net v2 跑实验，官方给出的普通安装方式是：

pip install nnunetv2

如果你后面准备跟着本系列修改 Trainer、loss、augmentation 或 network architecture，建议使用可编辑安装。editable install 指的是：你从 GitHub 克隆源码，然后用 pip install -e . 安装。这样你修改本地源码后，Python 环境会直接使用修改后的代码。

git clone https://github.com/MIC-DKFZ/nnUNet.git
cd nnUNet
pip install -e .

两种方式怎么选？可以参考下表：

安装方式	适合人群	优点	注意点
`pip install nnunetv2`	只想跑通训练和推理	简单、干净	不方便改源码
`pip install -e .`	准备学习内部框架和自定义模块	适合调试和二次开发	需要自己管理源码目录

6. 创建三个核心目录

nnU-Net v2 不会把所有东西都塞进当前项目目录，而是依赖三个固定含义的存储位置。

环境变量	作用	里面通常有什么
`nnUNet_raw`	保存原始数据集，且必须符合 nnU-Net 数据集格式	`Dataset001_MyDataset`、`imagesTr`、`labelsTr`、`dataset.json`
`nnUNet_preprocessed`	保存预处理后的训练数据	重采样、归一化、裁剪之后的中间结果和 plans
`nnUNet_results`	保存训练结果和模型	checkpoint、日志、fold 结果、安装的预训练模型

你可以把它们放在大容量硬盘上，例如：

mkdir -p /data/nnUNet_raw
mkdir -p /data/nnUNet_preprocessed
mkdir -p /data/nnUNet_results

如果你只是本机学习，也可以放在家目录下：

mkdir -p ~/nnUNet_raw
mkdir -p ~/nnUNet_preprocessed
mkdir -p ~/nnUNet_results

7. 设置环境变量

在 Linux 或 macOS 中，可以先临时设置：

export nnUNet_raw="/data/nnUNet_raw"
export nnUNet_preprocessed="/data/nnUNet_preprocessed"
export nnUNet_results="/data/nnUNet_results"

临时设置只对当前终端有效。关闭终端后就会消失。更常见的做法是写入 ~/.bashrc 或 ~/.zshrc：

cat >> ~/.bashrc <<'EOF'
export nnUNet_raw="/data/nnUNet_raw"
export nnUNet_preprocessed="/data/nnUNet_preprocessed"
export nnUNet_results="/data/nnUNet_results"
EOF

source ~/.bashrc

如果你实际使用的是 ~/nnUNet_raw 这类路径，就把上面的 /data/... 改成你自己的真实路径。

Windows PowerShell 的写法不同：

$Env:nnUNet_raw = "C:/path/to/nnUNet_raw"
$Env:nnUNet_preprocessed = "C:/path/to/nnUNet_preprocessed"
$Env:nnUNet_results = "C:/path/to/nnUNet_results"

本系列后续命令以 Linux shell 为主。如果你在 Windows 上学习，建议使用 WSL2 + NVIDIA GPU 环境，路径和命令会更接近 Linux。

8. 验证安装是否成功

安装完成后，不要急着准备数据集。先做一个最小检查：

echo "$nnUNet_raw"
echo "$nnUNet_preprocessed"
echo "$nnUNet_results"

python - <<'PY'
import torch
print("torch:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
PY

nnUNetv2_plan_and_preprocess -h
nnUNetv2_train -h
nnUNetv2_predict -h

你希望看到：

三个 echo 命令都输出了你配置的路径，而不是空行。
torch.cuda.is_available() 在 GPU 环境中为 True。
nnUNetv2_plan_and_preprocess -h、nnUNetv2_train -h、nnUNetv2_predict -h 能打印帮助信息。

9. 常见安装问题

现象	常见原因	建议检查
`torch.cuda.is_available()` 是 `False`	PyTorch 装成 CPU 版，或驱动/CUDA 不匹配	重新用 PyTorch 官网选择器生成命令；检查 `nvidia-smi`
找不到 `nnUNetv2_train`	环境未激活，或安装失败	确认 `conda activate nnunetv2`；运行 `pip show nnunetv2`
nnU-Net 报路径未设置	三个环境变量为空或只在别的终端设置过	运行 `echo "$nnUNet_raw"` 等命令
预处理或训练时磁盘爆满	`nnUNet_preprocessed` 或 `nnUNet_results` 放在小磁盘	把三个目录放到大容量硬盘；提前确认剩余空间