Pyradiomics 这个库读作 “派-拉迪-奥米克斯”其实在医学影像分析圈子里已经不算新面孔了。做肿瘤影像组学、纹理特征提取、术前预测模型这类研究的同学基本都会遇到它。它能从 CT、MRI、PET 这些医学图像里一次性提取出上千个定量特征比如形状、灰度直方图、纹理矩阵等可以说是影像组学工作流里比较核心的一环。不过Pyradiomics 的安装并不总是那么顺手尤其是当你用 Anaconda 管理 Python 环境时经常会在源配置、虚拟环境、版本兼容这些环节上卡住。我最早装的时候也折腾了很久遇到过unavailableinvalidchannel: http 404 not found for channel anaconda/pkgs/free这种报错还有装完之后导入直接缺依赖的问题。这篇就完整记录一下我的安装过程和踩坑思路照着走基本能避掉大多数问题。内容适合打算系统学习影像组学、需要用 Pyradiomics 做特征提取的科研人员也适合刚接触 Anaconda 环境管理的新手参考。1. 先搞清楚 Pyradiomics 是什么安装路线才好选1.1 影像组学里的“特征计算器”Pyradiomics 的本质是一个基于 Python 的影像组学特征提取库。它的核心价值在于把一张医学图像通常还需要对应的 ROI 掩膜输入进去它就会自动计算出大量可量化的特征。这些特征分成几个层次第一层是形态特征描述病灶的形状、大小、表面积、体积等第二层是一阶灰度统计特征包括均值、方差、偏度、峰度、熵等第三层是纹理特征比如灰度共生矩阵GLCM、灰度游程矩阵GLRLM、灰度大小区域矩阵GLSZM、邻域灰度差分矩阵NGTDM和灰度依赖矩阵GLDM。这些特征组合起来就是后续机器学习建模最常用的输入变量。理解了这点你就能明白Pyradiomics 不是一个“装了就能跑”的小工具它对底层图像处理库是有要求的。它依赖 SimpleITK 来读写 DICOM/NIfTI 等格式依赖 numpy 做矩阵运算依赖 scipy 处理统计计算还涉及 pykwalify 做配置校验。所以安装时最大的风险就是这些依赖版本和你的 Python 环境不匹配。这也是为什么后面我强烈建议你用独立的虚拟环境来装而不是直接往 base 环境里塞。1.2 pip 和 conda为什么我推荐 pip在决定怎么装之前先讲清楚两条路线的区别。Pyradiomics 官方目前主推的安装方式是 pippip install pyradiomics。它会自动解析并帮你安装所有缺失的依赖包过程非常省事。而 conda 安装虽然也是标准方式但默认的 Anaconda 源里其实并没有完整的 pyradiomics 包你需要额外添加 conda-forge 通道或者使用rai这个渠道如果源没配置对就容易触发 404 报错。我自己试验下来30 秒内能装完的一定是 pipconda 有时要等好几轮源解析还容易解析失败。所以下面这篇教程主线步骤就是“Anaconda 虚拟环境 pip”副线讲 conda 怎么补救。另外补充一句很多人在搜索时会看到pip install pyradiomics和pip install pyradiomics-gpu两种说法。前者是最常规的 CPU 版本适用于绝大多数医学图像分析场景后者需要额外配置 CUDA 环境比较麻烦而且特征提取计算量没有大到必须上 GPU 的程度。个人建议先装普通版本跑通了再考虑其他。2. Anaconda 准备版本选择、下载与镜像源配置2.1 下载哪个 Anaconda 版本比较稳这一步是安装环境的基础操作但仍有很多人在这里踩坑。先说结论个人电脑上优先选择 Anaconda 官方 64 位安装包版本以较新的 2023.x 或 2024.x 为主安装时注意勾选 “Add Anaconda3 to my PATH environment variable” 这个选项。很多教程会提醒你别勾因为可能和系统自带 Python 冲突但如果你是专门做图像组学分析、不掺和其他开发项目直接勾选反而省事免得后面命令行里找不到 conda。关于 Anaconda 和 Miniconda 的选择一句话概括Anaconda 是“全家桶”默认带了几百个常用科学计算包适合图省事的用户Miniconda 是“轻量版”只包含 conda 和 Python其他包按需安装。如果你已经对 Python 生态比较熟悉或者电脑空间紧张装 Miniconda 完全够用Pyradiomics 所需的依赖反正都要我们自己装。如果是新手且空间充裕就选 Anaconda后续操作起来更顺手。装完之后建议先做两件事第一在命令行输入conda --version看是否正常输出版本号第二输入python --version确认当前 Python 版本号。这里有个常见现象Anaconda 自带的是 Python 3.x 版本但系统里可能还装了其他 Python导致命令行输出的不是你预期的那一个。遇到这种情况不用慌看which python或where python的输出路径确认优先级即可。2.2 用清华源替换默认源解决“慢”和“404”两个老大难安装完 Anaconda 后你应该能感受到一个很真实的体验从官方源下载包特别慢动不动就超时还经常蹦出来一串UnavailableInvalidChannel: HTTP 404 NOT FOUND for channel anaconda/pkgs/free之类的红色报错。这个问题出现的原因并不复杂——官方源在部分地区连接不稳定同时某些旧版本的配置里默认还会去请求已经变更或失效的频道于是直接返回 404。我的做法是一劳永逸地切换到清华镜像源。依次在命令行输入以下命令conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ conda config --set show_channel_urls yes这四条通道分别对应 Anaconda 的主软件源、免费软件源、Windows 依赖源和社区扩展源。msys 通道其实主要给 Windows 下的某些编译工具用装 Pyradiomics 不一定用得上但提前加上没坏处。conda-forge 通道是最重要的因为 Pyradiomics、SimpleITK 等包在官方源里经常没有conda-forge 里基本都齐全。然后把show_channel_urls设置为 yes方便后面每次安装时能看到来自哪个源的包排查问题一目了然。设置完成后可以用conda config --show channels查看当前已生效的通道列表。如果哪天觉得源配置乱了想全部恢复默认输入conda config --remove-key channels这个命令会直接把本地的 channel 配置全部清空比一条条手动删要省心很多也避免了删除镜像源时漏删的隐患。2.3 换源之后还是 404先定位是哪个频道的问题换源之后大多数下载和更新问题都能解决但有些电脑上依然会弹HTTP 404 NOT FOUND for channel anaconda/pkgs/free这种错误。原因很可能是本地 conda 配置里还残留着旧源地址或者.condarc文件里同时写了多个互相冲突的地址。这时候我建议直接查看用户目录下的.condarc文件Windows 路径C:\Users\用户名\.condarcLinux/macOS 路径~/.condarc用文本编辑器打开手动把里面所有https://repo.anaconda.com开头的行替换成清华镜像地址。如果你之前执行过conda config --remove-key channels这个文件也会被清空。除了 404还要注意另一种常见情况你已经配了清华源但提示CondaHTTPError: HTTP 000 CONNECTION FAILED这说明当前网络跟镜像站之间连接不畅可以检查一下代理设置或者临时把ssl_verify关掉仅在信任的局域网环境里建议这么做正常不推荐conda config --set ssl_verify false跑通源之后你会发现后面所有 conda 操作都顺了很多创建环境、安装依赖这些动作基本是秒级响应。3. 创建独立虚拟环境让依赖不打架3.1 为什么强烈建议单独建一个环境很多新手拿到 Anaconda 之后习惯直接在 base 环境里满世界安装包等到某一天一个包升级另一个包崩掉的时候才追悔莫及。Pyradiomics 恰好就是一个很典型的容易“打架”的库它依赖的 numpy、scipy、SimpleITK 版本范围比较严格而你 base 环境里可能装着最新版 numpy或者按其他项目需要早就升级到了新版本这样在导入 radiomics 时很容易报错典型的错误长这样RuntimeError: module compiled against API version a but this version of numpy is ...如果出现这种提示说明当前环境的 numpy 和 Pyradiomics 编译时的版本不兼容。与其去赌 base 环境里各种包的版本恰好都合适不如花一分钟新建一个专门跑影像组学的环境把环境保存成一个干净、可控的状态。这样做还有一个额外的好处以后某个项目的依赖坏了直接删掉这个环境重建就行完全不影响其他工作。3.2 创建与激活环境的完整步骤创建虚拟环境的命令非常简单但有几个关键参数值得展开讲。conda create -n radiomics_env python3.9 -y这里-n radiomics_env是给环境命名名字按自己习惯取就行。关键在于python3.9为什么我特别强调指定 Python 版本因为 Pyradiomics 官方一些较早的版本对 3.10 以上新版本的支持偶尔会出现预编译包缺失的问题3.8 和 3.9 是兼容性最好的区间。指定版本号后conda 会自动拉取对应版本的 Python省得以后各个包之间因为解释器版本不同而起冲突。命令后面的-y意思是自动确认不需要安装过程中再手动敲 y。执行完成后激活环境Windowsconda activate radiomics_envLinux/macOSsource activate radiomics_env激活后命令行前边会多出一个(radiomics_env)前缀这代表你当前已经处于该虚拟环境里。这个前缀很重要后面你安装的所有包都只会进到这个环境不会污染全局。3.3 环境管理的一些常用命令环境建好后有几个命令你大概率用得上。查看当前所有环境conda env list或者conda info --envs这两条都会列出一个环境列表带星号或括号的那个就是当前激活的环境。如果某天这个环境不再需要可以退出去再删除conda deactivate conda env remove -n radiomics_env还有个细节很多人创建环境时想更改默认路径把环境建到 D 盘之类的非系统盘因为 C 盘空间紧张。这个可以通过修改.condarc里的envs_dirs配置来实现但实际使用中如果不是特别缺空间我建议保持默认路径因为部分 IDE 和工具扫描 conda 环境时对非默认路径的支持不算完美。4. 安装 Pyradiomics两种方式与验证4.1 pip 安装我的首选方案在已经激活的radiomics_env环境下直接执行pip install pyradiomics如果一切顺利pip 会开始下载 pyradiomics 及其依赖包整个过程通常在几十秒到几分钟之间。安装完成后命令行会显示类似Successfully installed pyradiomics-3.1.0 ...的信息。这里我想提醒一个新手容易困惑的点很多人会疑惑“我该不该升级 pip 版本后再安装”其实不用刻意升级默认的 pip 版本够用除非收到了明确的提示。如果 pip 默认源下载比较慢你也可以指定使用清华 PyPI 镜像pip install pyradiomics -i https://pypi.tuna.tsinghua.edu.cn/simple这种方式有时候比 conda 走镜像更快因为它直接走 PyPI 的 CDN 缓存。4.2 conda 安装怎么做以及为什么不作为首选如果你确实想用 conda 来装可以在激活环境后执行conda install -c conda-forge pyradiomics这一条会从 conda-forge 通道拉取包但受限于 conda 的依赖解析机制你经常要等很长时间才能完成。而且有些历史版本在 conda-forge 上并没有对应的构建可能解析到一半就自动放弃了。所以我的态度是conda install 可以试但别把它当成首选路径。万一你尝试了conda install pyradiomics并且遇到PackagesNotFoundError不用慌直接用 pip 装就行不影响最终结果。还有一点需要说明conda install -c raqd/pyradiomics pyradiomics这个写法在较老教程里很常见但这个通道现在已经不再维护不推荐使用。如果你照着旧教程敲了这类命令并且报错直接忽略即可。4.3 验证安装不是导入成功就万事大吉装完之后最基本的验证方式是打开 Python 解释器python然后在 Python 里输入import radiomics print(radiomics.__version__)如果没有任何报错并且输出了类似3.1.0的版本号说明库已经导入成功。不过我建议你再多走一步做一个最小化的单特征提取测试。最简单的方式是使用官方自带的示例数据。Pyradiomics 安装时可能会附带少量测试数据或者你可以直接从官方 GitHub 仓库下载。官方仓库里有一个examples目录里面有示例图片和掩膜文件。控制台快速测试可以执行pyradiomics path/to/image.nii path/to/mask.nii --param path/to/Params.yaml -o path/to/output.csv如果这个命令能跑出 CSV 文件才算真正把环境跑通了。我见过不少情况import 时正常但真到读取 NIfTI、计算特征时报出一堆底层库的错误。因此这里我强烈建议导入成功只是第一步能跑通官方案例才是真的没问题。5. PyCharm 与 Jupyter 环境接入5.1 把虚拟环境接到 PyCharm 里很多科研人员的日常也不是纯命令行操作更多是用 PyCharm 写代码、调参和调试。如果你用的是 PyCharm需要把刚建好的 conda 环境配置为项目解释器。步骤很简单打开 PyCharm进入File - Settings - Project: xxx - Python Interpreter点击右上角的齿轮图标选Add Interpreter - Add Local Interpreter。在弹出的窗口里左侧选Conda Environment然后选择Existing environment在下拉列表里找到radiomics_env。如果下拉列表没显示可以直接点右侧的...按钮找到环境目录下的python.exeWindows 路径通常是C:\Users\用户名\anaconda3\envs\radiomics_env\python.exeLinux/macOS 路径通常是/home/用户名/anaconda3/envs/radiomics_env/bin/python选好之后点 OKPyCharm 就会以这个环境作为项目解释器。之后在项目里执行import radiomics就能用到我们刚才安装好的库了。这里有一个我个人遇到过的坑如果你在 PyCharm 里创建新文件时右下角解释器显示的是Python 3.9 (radiomics_env)但运行时还是报ModuleNotFoundError: No module named radiomics一般不是环境选错了而是 PyCharm 的终端没有激活这个环境。解决办法是在 PyCharm 里打开 Terminal 面板手动执行conda activate radiomics_env然后再运行脚本。5.2 Jupyter Notebook 怎么用上这个环境如果你习惯用 Jupyter Notebook 做分析和记录实验也需要额外配置一下因为 Anaconda 自带的 Jupyter 默认只认识 base 环境。要让 Notebook 内核切换成我们的radiomics_env先在激活的环境里安装 ipykernelconda activate radiomics_env pip install ipykernel python -m ipykernel install --user --name radiomics_env --display-name Pyradiomics这条命令会把这个环境注册到 Jupyter 的内核列表里并给内核起一个显示名。重启 Jupyter Notebook 后新建 Notebook 时在Kernel - Change Kernel里选择Pyradiomics你再导入 radiomics 就不会有问题了。如果你用的是 Jupyter Lab操作方式完全一样。多说一句python -m ipykernel install这步很容易被忽略缺失的话你在 Jupyter 里看到的只有默认的 Python 3 内核怎么切都切不过去误以为环境没建好。很多人在这里浪费了不少时间其实就差这一行注册命令。6. 高频报错与排查心得整理6.1 让人头疼的UnavailableInvalidChannel: HTTP 404 NOT FOUND这个报错在 Anaconda 使用过程中出现频率极高搜索引擎里相关热搜词也是一大堆。报错信息通常会带具体频道名比如pkgs/free、pkgs/msys或者pkgs/r。它出现的核心原因就是在 conda 的配置里某个 channel 地址已经失效或配置错误conda 每次去请求时都找不到对应的文件夹。我的排查顺序是这样的第一先执行conda config --show channels看当前配置了哪些源。第二如果看到官方源或过期源残留执行conda config --remove-key channels清空后重新添加清华源。第三如果清空后依然报错直接手动编辑.condarc文件确保里面没有指向repo.anaconda.com的地址。第四如果你之前安装过某个旧的 Anaconda 版本考虑直接升级或者重装 Anaconda因为旧版本默认配置里就可能包含这些失效频道。要注意的是这个 404 报错并不影响你已经装好的包但它会阻止后续的 conda 安装和更新操作所以必须解决。有时候执行conda update conda也会触发这类源检查这就解释了为什么很多人一执行更新就报 404。6.2 安装超时、下载慢多半是源的问题如果你是直接用 pip 默认源安装 Pyradiomics 时发生超时最常见原因是默认源在国外网络连接不稳定。解决办法有两个一是添加-i参数临时指定清华源二是把清华源设为全局默认。全局设置方法pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple设置之后后续所有 pip 安装都会走清华源。这个方法也可用于以后安装其他 Python 包比如 pandas、scikit-learn 等一并提速。如果你用的是 conda 安装超时那就回到上面 2.2 节的清华镜像配置。6.3 SimpleITK 和 numpy 版本冲突怎么处理Pyradiomics 最依赖的三个核心库是 SimpleITK、numpy 和 scipy。其中 SimpleITK 负责医学图像读写与预处理numpy 负责数组运算scipy 负责统计与部分矩阵计算。三者配套出现问题最典型的表现是安装 pyradiomics 的时候明明成功了但import radiomics时报DLL load failed或者undefined symbol之类的错误。这种情况通常是环境中 SimpleITK 版本过新与某些旧版 C 库不兼容。我的建议是让你的环境里保持 SimpleITK 的版本和 Pyradiomics 官方要求一致Pyradiomics 3.1.0 配套比较稳定的 SimpleITK 版本一般在 2.x 区间。如果不确定直接重新安装 pyradiomics让它自动解析依赖pip uninstall pyradiomics -y pip install pyradiomics --upgrade另外如果环境里有多个 numpy 版本残留也可能导致动态库加载混乱可以在虚拟环境里强制重装一下 numpypip install --upgrade --force-reinstall numpy注意这个强制重装是在虚拟环境里执行别在 base 环境操作否则可能影响其他项目。6.4 其他遇到过的杂项问题问题现象常见原因解决办法命令行找不到conda命令安装时未加入 PATH 或环境变量未生效Windows 下重新打开命令行Linux 下执行source ~/.bashrc或手动把 anaconda3/bin 加入 PATH安装完成后 Anaconda Navigator 启动失败版本不兼容或启动文件损坏先conda update anaconda-navigator更新再启动不常用的话也可以忽略直接用命令行在导入 radiomics 时提示No module named pykwalify依赖丢失pip install pykwalify并重新安装 pyradiomicsLinux 系统下激活环境后路径前缀不显示终端未刷新执行source activate radiomics_env再检查或重新登录终端会话Pyradiomics 计算时读取 NIfTI 文件报错文件路径或格式问题确认路径无中文及空格用 nibabel 或 SimpleITK 单独读一次文件确认可正常解码Pyradiomics 官方也提供了很完整的文档和示例如果遇到上面没覆盖到的问题可以先在 GitHub 的 issues 里搜索错误码绝大部分问题和解决方案其实都已经有现成记录。在整个安装和使用的过程中我个人最大的体会是Anaconda 这个工具本身并不难难的是各种源配置、环境变量、依赖兼容之间的组合问题。所以如果你是新手上路我的建议是哪怕多花两分钟建个独立环境也好过在 base 环境里反复折腾。环境干净了后面无论是跑官方案例、批量提取特征还是和同事共享代码都会省心很多。最后留一个实用小技巧装好 Pyradiomics 之后把环境的conda list导出一份存成environment.yml以后换机器或者重建环境时一条conda env create -f environment.yml就能复现今天的全部配置。