1. 为什么医学影像AI入门首选MONAI

医学影像AI这几年热度一直很高，CT、MRI、病理切片这些数据，和自然图像不一样，天然就是三维甚至四维的，通道数、空间分辨率、体素间距、方向信息，每一个都和常规的计算机视觉任务有差别。MONAI（Medical Open Network for AI）就是专门为这个场景打造的开源框架，基于PyTorch构建，由伦敦国王学院、NIH等机构牵头发起，目前已经是医学影像领域事实上的基础工具之一。

我在实际项目里最大的感受是，它把医学影像处理中那些高频、重复、容易写错的底层环节全部封装好了。比如加载NIfTI格式的医学影像，用普通PyTorch写要自己处理affine矩阵、处理方向朝向、处理重采样，稍不注意体素间距就乱了；MONAI提供了一个LoadImage接口，配合Compose链式处理，几行代码就能搞定一个标准的训练管线。再比如它内置了残差UNet、Swin UNETR、UNETR等大量预定义网络结构，做分割、分类、配准、检测都有对应的模型，不用从零搭网络。

这篇文章就是给准备上手MONAI的朋友准备的安装全流程指南。我会从环境规划讲到具体命令，再讲到验证、排错，最后补充MONAI生态里其他组件的安装方式。内容覆盖从Windows到Linux，从纯CPU到多卡GPU的常见场景。如果你是医学影像相关的研究生、算法工程师，或者只是对3D医学数据处理感兴趣的开发者，跟着这篇文章走，大概率能避开我在安装阶段踩过的所有坑。

先说一句：MONAI虽然叫框架，但实际上不是一个单体软件，而是分成MONAI Core（核心库）、MONAI Label（交互式标注）、MONAI Deploy（部署工具链）等多个部分。当前这篇聚焦最核心的MONAI Core安装，这也是绝大多数模型训练和数据处理场景要用到的部分。

2. 开始安装前必须想清楚的几件事

2.1 MONAI与PyTorch、Python、CUDA的版本匹配关系

Monai不是一个独立的深度学习引擎，它只是PyTorch的上层封装，所以你的PyTorch版本直接决定了MONAI能不能跑、跑得顺不顺。先看官方给出的依赖关系：MONAI支持Python 3.9到3.12，PyTorch 1.9到2.6的多数版本，但这只是一个非常宽泛的区间，实际安装时我建议遵循"PyTorch版本优先"的原则。

原因很简单：MONAI本身对CUDA没有直接依赖，它是通过PyTorch来调用GPU的。只要PyTorch能用CUDA，MONAI就能用CUDA。反过来，如果PyTorch装的是CPU版，那MONAI跑得再欢也不会用GPU。所以在安装顺序上，永远是先确定PyTorch版本，再装MONAI。

下面是我测试过的稳定组合，可以直接参考：

这四组我都实际跑过MONAI的2D/3D分割训练任务。组合A的兼容性最好，MONAI里几乎所有功能都不会报错；组合B适合想同时用PyTorch 2.x新特性的用户；组合C要注意NVIDIA驱动得比较新，否则会提示CUDA版本不匹配；组合D适合历史项目。

怎么确认自己的NVIDIA驱动支持哪个CUDA版本？在终端里执行nvidia-smi，右上角有个"CUDA Version"字样，那表示你的驱动最高支持到这个CUDA版本。比如显示CUDA Version: 12.1，那你可以放心安装CUDA 12.1或更低的版本对应的PyTorch，千万别装比它更高的。

2.2 选择pip安装还是conda安装

MONAI官方给了两种安装方式：pip install "monai"和conda install -c conda-forge monai。我自己实际用过两种，结论是：推荐pip，理由有三点。

第一，MONAI的PyPI包更新非常及时，新的预训练模型或新功能合入后，基本一两天内就能通过pip升级，而conda-forge渠道的包有时会滞后几个版本。第二，pip安装MONAI时能自动解析PyTorch的版本依赖，虽然这个依赖判断不够智能，但至少不会装出完全跑不起来的组合。第三，pip装出来的虚拟环境和conda装的，在系统层面的隔离性没有本质区别。

那conda还有没有存在价值？有。我依然建议用conda管理Python环境本身，也就是说：用conda创建干净的Python环境，然后在环境里用pip安装PyTorch和MONAI。这种混合方案既享受了conda管理Python版本和虚拟环境的便利，又拿到了pip安装包的最新版本资源，是我个人最推荐的做法。

当然，如果你坚持全程conda，可以考虑用conda先装好PyTorch和Python依赖，再用pip装MONAI，这样能把版本冲突的概率降到最低。

2.3 确定自己的组件边界：你只需要Core还是全套

在动手之前，想清楚你需要的是MONAI的哪个部分。MONAI Core是基础库，做数据处理、网络构建、训练和评估都在这里面；MONAI Label是一个标注工具前端，它需要配合3D Slicer使用；MONAI Deploy是专门做模型部署的工具链，把训练好的模型打包成可以独立运行的应用。

如果只是跑模型训练和实验，只装MONAI Core就够了，装Label和Deploy会引入额外的依赖，比如Label会要求安装某些针对交互式标注的网络层，Deploy会要求安装它自己的App SDK。这些都会增加安装失败的排查难度。

对于第一次上手的朋友，我的建议就一句话：先只装MONAI Core，把训练流程跑通，再按需补装其他组件。

3. 环境准备与安装全流程详解

3.1 创建干净的conda虚拟环境

安装Miniconda还是Anaconda？都可以，但我个人推荐Miniconda，因为Anaconda自带的两百多个预装包对MONAI的安装没有实际帮助，反而会因为numpy版本、matplotlib版本等被conda来回折腾。Miniconda轻量，需要的包可以自己按需装。

到Miniconda官网下载对应系统的安装包，Windows下选Miniconda3 Windows 64-bit的exe，Linux下选Miniconda3-latest-Linux-x86_64.sh。安装过程一路默认就行。

装好之后，打开终端（Windows下是Anaconda Prompt或PowerShell），先更新conda本身：

conda update -n base -c defaults conda

然后创建MONAI的专属环境，我建议环境的Python版本直接定位到3.10，这是MONAI官方支持最稳的版本区间：

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

激活之后，检查一下Python版本：

python --version

输出Python 3.10.x就对了。这里有一个很小的细节：你在终端输入python，注意看路径里的环境名，如果显示的是(monai)前缀，说明已经在虚拟环境里了。后续所有安装操作，都必须在(monai)环境激活的状态下进行，否则会装到base环境里，后面import时定位不到版本。

3.2 安装PyTorch：GPU版还是CPU版

PyTorch是MONAI的地基，版本和CUDA的匹配问题都在这一环节解决。先判断自己的机器有没有NVIDIA GPU：

nvidia-smi

如果提示NVIDIA-SMI has failed because GPU is not detected，说明没有可用GPU，安装CPU版即可。如果有GPU，看右上角支持的CUDA版本。

以CUDA 11.8为例，定义的安装命令是：

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

如果驱动支持的CUDA版本是12.1，换用：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

CPU版直接：

pip install torch torchvision

装完后在Python环境里验证：

import torch print(torch.__version__) print(torch.cuda.is_available())

如果你能看到True，说明PyTorch已经能用GPU了。这一步通过了，MONAI才能调得动GPU。很多MONAI安装教程跳过了这步，直接装MONAI，等到跑训练时才发现用的是CPU，训练速度差几十倍，回过头来重新装PyTorch，浪费时间又容易把环境搞乱。

还有一点容易忽略：不要用conda默认源装PyTorch，conda默认源里的PyTorch经常是CPU版或旧版，编译参数也比较保守。直接用上面PyTorch官方指定的index-url是最稳妥的。

3.3 通过pip正式安装MONAI

PyTorch配置好后，MONAI的安装就很简单了：

pip install "monai"

这个命令会安装MONAI Core的最新稳定版，同时自动带上它依赖的numpy、torch、torchvision、Pillow、tqdm、fire、nibabel等基础库。因为前面已经有PyTorch，pip检查依赖时不会重复下载。

等进度条跑完，确认一下：

pip show monai

能看到版本号和安装路径。当前时间点最新稳定版是1.4.x，如果你处于Python 3.10环境，这个版本没有任何运行障碍。想指定版本也可以：

pip install "monai==1.4.0"

不过没有特殊情况的话，直接用最新版就行，MONAI的API向后兼容做得不错，不需要刻意锁版本。

3.4 补充安装医学影像处理和训练辅助库

MONAI Core虽然集成了大量数据处理能力，但有几个在真实项目中常用的库默认不会装，需要手动补上。

• itk：做医学影像格式转换和读取时很常用，MONAI里如果要用到某些特殊格式会调用它。
• SimpleITK：我强烈建议装，很多预训练模型教程和MONAI官方示例中会用到它读写医学图像。
• matplotlib：可视化切片和训练曲线用的，虽然MONAI自己不强制，但看结果时几乎离不开。
• tensorboard：训练过程中的损失曲线和指标可视化，MONAI的TensorBoardStatsHandler需要它。
• jupyter：跑官方Notebook教程必备。

一次装齐：

pip install itk SimpleITK matplotlib tensorboard jupyter

有些MONAI示例会用到dicom2nifti、tqdm、scikit-learn等，这些按需安装即可，不强求一次性装齐。

3.5 完整安装总览：一条命令清单快速复现环境

为了省去重复劳动，我把整个流程整理成一份可以直接复制的命令清单。以下命令假设你已装好Miniconda并处于base环境：

# 创建环境 conda create -n monai python=3.10 -y conda activate monai # 安装GPU版PyTorch（CUDA 11.8示例） pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 安装MONAI核心库 pip install "monai" # 辅助库 pip install itk SimpleITK matplotlib tensorboard jupyter

这份清单在Linux和Windows的conda环境里都能直接跑。macOS用户如果没有NVIDIA GPU，PyTorch直接用CPU版即可，MONAI大部分CPU推理和训练功能仍然可用，只是3D网络的训练速度会明显慢一些。

4. 安装完成后的标准验证流程

4.1 用import和版本号确认安装正确

安装完先别急着跑训练，做一套标准的健康检查。打开Python交互环境：

import monai print(monai.__version__)

能打印出版本号，说明MONAI核心库本身没装错。接着检查MONAI引用的PyTorch是否正常：

import torch print(torch.__version__) print(torch.cuda.is_available())

这两条和前面验证PyTorch的一致，但是放在这里再次确认是有意义的。因为MONAI在import时可能会触发一些底层的PyTorch操作，如果PyTorch本身有问题，这一步就会直接暴露。

我遇到过这样的情况：PyTorch安装时没报错，torch.cuda.is_available()也返回True，但import MONAI后却提示某个CUDA算子找不到。原因往往在于PyTorch的CUDA运行时版本和当前系统层的NVIDIA驱动不完全兼容。这种情况比较麻烦，建议直接用MONAI的诊断命令检查：

from monai.config import print_config print_config()

这条命令会输出一份完整的诊断报告，包括MONAI版本、Python版本、PyTorch版本、是否启用CUDA、NVIDIA驱动版本、可用的GPU数量等关键信息。看到CUDA available为True，基本可以确定环境健康。

4.2 用MONAI自带的数据集和网络做一次冒烟测试

版本和CUDA都检查通过后，最后一步冒烟测试：加载一个MONAI内置的数据样例，跑一遍前向传播，确保训练管线没有隐藏问题。我通常用下面的脚本：

import torch import monai from monai.transforms import LoadImage, EnsureChannelFirst, ScaleIntensity from monai.networks.nets import UNet # 创建一个随机医学图像模拟输入 x = torch.randn(1, 1, 64, 64, 64) # 定义3D UNet model = UNet( spatial_dims=3, in_channels=1, out_channels=2, channels=(16, 32, 64), strides=(2, 2), ) # CPU或GPU device = torch.device("cuda" if torch.cuda.is_available() else "cpu") model = model.to(device) x = x.to(device) output = model(x) print("输出尺寸:", output.shape)

如果能看到输出尺寸: torch.Size([1, 2, 64, 64, 64])，说明MONAI的模型定义、数据形状处理、设备分配都正常。这个测试比import更加严格，因为它真正执行了一次前向计算，能排查出诸如CUDA内存分配、浮点精度、数据布局等问题。

4.3 查看MONAI提供了哪些内置功能

安装完毕后，可以快速了解一下MONAI的模块体系，方便后续查阅。执行：

import monai print(dir(monai))

输出里会看到networks、transforms、data、losses、metrics、engines等模块名。其中：

• monai.transforms：数据预处理和增强工具，是最高频使用的模块。
• monai.networks：预定义网络结构，包括UNet、UNETR、SwinUNETR、DynUNet等。
• monai.engines：训练和评估的封装引擎，基于PyTorch Ignite，也可以不用它而自己写训练循环。
• monai.losses：医学影像场景常用损失函数，如DiceLoss、DiceCELoss、FocalLoss等。
• monai.metrics：Dice指标、表面距离等评估工具。

如果你懒得全部记住，一个print_config()加一个dir(monai)就能帮你快速掌握这个库的边界。

5. 安装阶段最容易踩的坑与排查链路

5.1 坑一：conda和pip混装导致monai无法import

这个问题我几乎每次帮同事排查环境时都会遇到。症状是：明明pip show monai显示已安装，但在Python里import monai却提示ModuleNotFoundError。

排查链路是这样的：先在终端里执行which python和which pip，看看两者是否指向同一个解释器。如果分别指向不同路径，比如which python指向conda环境的/opt/miniconda3/envs/monai/bin/python，但which pip指向系统的/usr/local/bin/pip，那就说明pip命令用的是全局环境，装到了系统目录里，而python解释器用的是conda环境。

解决方法是：明确用python的-m参数调起pip。

python -m pip install "monai"

这样能保证包一定装到当前python解释器对应的环境中。养成这个习惯之后，后续装什么包都能省去很多烦恼。

5.2 坑二：PyTorch的CUDA版本与系统驱动不匹配

这个坑的典型表现是：PyTorch装好后，torch.cuda.is_available()返回True，但真正跑MONAI训练时，程序刚开始就崩掉，或者提示CUDA error: no kernel image is available for execution on the device。

这通常是因为PyTorch的CUDA编译版本高于驱动支持的CUDA版本。前面说过，用nvidia-smi查看驱动支持的CUDA版本号，假设显示12.1，却用--index-url https://download.pytorch.org/whl/cu124装了CUDA 12.4的PyTorch，就会出现这个错误。

解决办法也很直接：pip uninstall torch torchvision后，换成驱动支持范围内版本的PyTorch。如果驱动版本过低，也可以考虑更新NVIDIA驱动，但我更建议先压低PyTorch的CUDA版本，毕竟升级驱动有时候会遇到系统兼容性问题，风险更大。

5.3 坑三：国内环境下载缓慢或超时

MONAI本身很小，但PyTorch、itk这些依赖包体积动辄几百MB，国内直连下载确实容易慢。这个问题的常规解法是pip镜像和conda镜像，我实测下来稳定好用。

pip配置镜像：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

这样配置后，后续所有的pip安装都会走清华镜像，下载速度能提升几十倍。需要注意，配置镜像后再安装PyTorch时，如果还加--index-url参数指向PyTorch官方地址，会覆盖全局镜像设置，装PyTorch时可以直接用镜像源安装，但这样拿到的PyTorch版本大概率是CPU版。想装GPU版时，按官方命令走就行，下载速度慢一点就耐心等，或者用支持续传的下载工具先下好whl文件再本地安装。

conda镜像同理，在用户目录生成.condarc文件并写入：

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

5.4 坑四：Linux服务器上缺libGL.so.1

这个问题在Ubuntu服务器上尤其常见。症状：安装完MONAI后，import时直接报错，提示找不到libGL.so.1。

根因是MONAI在import时默认加载图像处理相关的底层库，这些库依赖OpenGL运行时。而很多云服务器为了精简没装图形库。解决办法：

sudo apt update sudo apt install libgl1

还有一部分提示缺少libgomp.so.1的情况，安装libgomp1即可。这类问题本质上不属于Python包依赖，而是操作系统动态库缺失，所以用pip和conda都解决不了，记住系统的包管理器才是处理工具。

5.5 坑五：Windows下PowerShell执行策略与报错

Windows上如果直接用PowerShell运行conda activate monai，可能会遇到conda: The term 'conda' is not recognized或执行策略限制。前者一般是Anaconda安装时没勾选自动添加环境变量，后者是Windows的安全策略限制。

前者在安装Anaconda时选上"Add Anaconda3 to my PATH environment variable"，或者手动把Anaconda的Scripts目录加到PATH。后者是权限问题，以管理员身份打开PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

然后按Y确认。这一行命令能解决大部分Windows下conda命令无法执行的问题。

5.6 踩坑总结：环境检查清单

把你排查时的顺序总结成一份清单，每次环境出问题按这个顺序过一遍：

1. which python与which pip是否对应同一个环境。
2. python -c "import torch; print(torch.cuda.is_available())"是否能输出True。
3. python -c "from monai.config import print_config; print_config()"是否报告CUDA可用。
4. nvidia-smi显示的CUDA版本是否不低于PyTorch的CUDA编译版本。
5. 是否缺少libGL等系统级动态库。
6. 是否在正确的虚拟环境中执行了安装命令。

这套链路排查完，90%以上的安装问题都能定位到根因。

6. 进阶：MONAI生态的延伸安装

6.1 一次装全MONAI Core的全部扩展特性

如果你不想在跑某个功能时频繁补装依赖，可以直接安装MONAI的完整扩展也可以规避这个坑。MONAI的某些可选功能在基础安装中默认不启用，比如monai[all]的安装方式会带上所有可选依赖：

pip install "monai[all]"

这会额外安装用于图像重采样的scipy，用于3D可视化交互的ipython、ipywidgets，以及一些数据格式支持库。体积不小，但好处是一劳永逸，后续跑官方教程时不会被各种ImportError打断。如果你更希望保持环境精简，可以先跳过这个选项，遇到缺库时按错误提示逐个安装。

6.2 安装MONAI Label并联动3D Slicer

MONAI Label是用于交互式医学影像标注的框架，和3D Slicer配合使用。安装命令很简单：

pip install monai-label

启动服务后，在3D Slicer中安装MONAI Label插件，就能连接本地或远程的标注服务。这套流程尤其适合做肺结节、肝脏、脑肿瘤等器官分割标注的场景，医生或标注员可以在3D Slicer界面里画几笔，AI模型就自动生成预分割结果，然后人工修正。从安装到跑通前后端，大概一小时内能完成。

6.3 安装MONAI Deploy工具链

如果你的目标是把训练好的模型打包成临床可用的推理应用，需要装MONAI Deploy：

pip install monai-deploy

它会拉取对应的App SDK和运行时，允许你把MONAI训练出的模型封装成支持医学图像输入输出的可执行程序。这个流程比标准PyTorch的TorchScript部署多了一层医学影像格式处理能力，比如DICOM文件的接收和解析。

6.4 用Docker镜像快速体验MONAI

如果你不想在本机折腾环境，或者需要复现别人的实验结果，NVIDIA GPU Cloud上就有打包好的MONAI镜像，MONAI官方也提供了发布在NVIDIA NGC的容器镜像。先安装好Docker和NVIDIA Container Toolkit，然后直接：

docker pull nvcr.io/nvidia/pytorch:24.01-py3

MONAI完全兼容NVIDIA PyTorch容器，进入容器后：

pip install "monai"

就可以用了。这种方式对Linux服务器做多机、多人共同开发特别友好，避免每个人的本地环境不一致导致复现困难。

需要提醒的是，Docker镜像通常体积很大，下载耗时较长，而且拉取镜像时的网络问题和前面说的下载问题是一致的，建议提前把容器镜像源配好。

7. 版本升级与日常维护建议

MONAI的迭代速度很快，几乎每个月都会发布新版本，有时是为了修bug，有时是加新功能或新预训练模型。两个原则建议从一开始就遵守。

第一，不要轻易在跑了一半的项目中升级MONAI版本。即使MONAI承诺API向后兼容，但版本跨度太大时，个别接口的默认行为可能已经变化，到时排查起问题来非常费时间。我自己的项目习惯是：项目启动时记录环境版本，用pip freeze > requirements.txt导出依赖清单，确保环境可以重建。

第二，需要升级时，先看官方Release Notes。重点看Breaking Changes部分，确认自己的代码是否用了被改动的接口。升级命令仍然是：

pip install -U "monai"

升级完成后，重新跑一遍前文中的冒烟测试脚本，用最小的成本确认新版本没有破坏现有功能。

另外，如果长时间不用的环境出现了import monai报错，首先怀疑的是Python或PyTorch版本被其他操作悄悄改了。用conda list对比一下环境里关键包的版本，一般能快速定位问题。

根据我个人经验，MONAI的安装其实没有想象中复杂，但环境匹配、版本管理、系统依赖这三类问题，几乎能覆盖掉安装阶段90%的报错。把这篇文章里的清单和方法存好，你后续使用MONAI的绝大部分时间都会花在真正的业务代码上，而不是折腾环境。