简介：Pyrosetta 是 Rosetta 蛋白质建模套件的 Python 接口，能够用于蛋白质结构预测、分子对接与设计等生物信息学计算。这份安装指南代码包专门服务需要快速部署 Pyrosetta 的 Python 研究者与开发者，其内容围绕 conda 安装路线展开，重点梳理了镜像源下载缓慢、依赖冲突、导入失败等高频故障的处理策略。包体仅 4KB，共 3 个文件，其中 html 文档描述完整安装流程，inscode 代码片段可辅助核对命令，gitignore 文件则用于规范工程目录，适合轻量查阅与对照使用。指南以conda install pyrosetta为主线，同时给出多个备选镜像源地址，安装完成后通过import pyrosetta即可验证是否成功；针对网络状况不佳、版本不兼容或系统依赖缺失等场景，也逐一给出了可操作的排错建议。目前已有 112 人学习浏览，对于想避开踩坑、节省环境配置时间的研究者来说，是一份很实用的速查资料。
1. PyRosetta 安装为什么总在最后一步翻车：先把许可证、通道和平台三件事定下来
用惯 pip 的人第一次装 PyRosetta，十有八九会在最后一步翻车：conda install跑到一半提示认证失败，或者import pyrosetta成功之后init()直接卡死。原因很简单，PyRosetta 不走普通 pip 生态的认证校验，它把许可证嵌在 conda 通道的刷取流程里，拿不到官方签发的账号密码，后面全白搭。这其实不是难事，只是文档散，Linux、Windows、macOS 几种常见环境遇到的坑还各不一样。
这篇指南面向的是接下来要在本地或服务器上跑蛋白质建模、折叠、设计或打分脚本的开发者。目标很实在：搞清选哪种安装方式；用 conda 把 PyRosetta 装到能跑通init()；跑完自检和一个最小打分协议；最后把许可证、通道、版本标签、数据库路径这些坑一次性说穿。跟着命令走，半小时内能见到底；遇到报错，也能从排查清单里找到对应的解法。
2. 安装方式选型：conda、Docker 与源码编译到底差在哪
2.1 三种分发渠道的真实差异：发布节奏、许可证与依赖范围
PyRosetta 官方目前主要维护三条分发路线：conda 通道、Docker 镜像、源码编译。三者的差异不只是安装命令不同，背后牵扯发布节奏、许可证校验方式、依赖隔离程度，选错一条路，后面所有脚本都可能跟着遭殃。
| 渠道 | 发布节奏 | 依赖管理 | 许可证校验 | 最适合谁 |
|---|---|---|---|---|
| conda 通道 | 官方频繁推送 stable / update / rolling 三档 | 由 conda 统一管理，环境隔离干净 | 安装时输入用户名密码，全局生效 | 绝大多数本地开发者、跑实验脚本的人 |
| Docker 镜像 | 随官方发版更新，镜像体积大 | 完全隔离，系统级依赖也被封装 | 进容器时配置账号信息 | Windows 用户、想快速试一下、需要整套环境复现的团队 |
| 源码编译 | 只跟着 Rosetta 主仓库节奏更新 | 依赖自己解决，SConstruct 体系独特 | 编译阶段绑定用户信息 | 需要定制底层编译参数、改 Rosetta 内部源码的少数人 |
从发布节奏看，conda 通道有三种标签：stable最保守，适合长时间跑实验；update带一些新功能和修复；rolling基本跟着最新代码走，容易踩到没验证完的边界行为。源码编译虽然是“听起来最厉害”的方案，但 Rosetta 的 SCons 构建体系对新手极不友好，一个 G++ 版本不匹配就能耗掉一整天，我一般只在需要改动 Rosetta 源码时才会碰这条线。
2.2 为什么我默认推 conda 路线：环境隔离与回滚成本
PyRosetta 的依赖里有 numpy、protobuf、python 版本这类敏感项，而它要求的 numpy 版本范围经常和深度学习环境冲突。如果直接装进 base 环境，装完 PyRosetta 再去跑 PyTorch，很容易出现“原本能用的模型突然报 numpy 类型错误”的情况。用 conda 独立环境隔离是成本最低的解法，conda create一条命令建立专属 env，出问题整个环境删掉重来，这才是后悔药。
动手之前先确认系统架构，PyRosetta 的安装包是按平台分发的，买错架构的坑比想象中常见：
# 确认 CPU 架构和发行版信息 uname -m cat /etc/os-release | head -3uname -m输出x86_64说明是 64 位 Intel/AMD 架构，aarch64说明是 ARM64 架构。PyRosetta 对不同平台的支持程度并不完全一致，装机前先拿这两条命令对照官方支持列表，比装到一半报错再回头排查要省事得多。我见过一个案例，某开发者拿了 x86_64 的安装包硬塞进 ARM 的服务器，conda 自检过了，init()直接段错误，最后只能用 Docker 镜像绕过去。
2.3 Docker 与 WSL 的适用场景：Windows 用户怎么选
Windows 原生不支持 PyRosetta 的 conda 包，官方认可的路线是 WSL2 或 Docker。WSL2 里跑 conda 和 Linux 体验基本一致，适合要长期在 Windows 上开发的人；Docker 则适合“我不想动系统环境，拉个镜像就跑”的场景。常见做法是先拉取官方维护的 PyRosetta 教程镜像，跑一句最小导入命令验证：
# 以下镜像名以官方 Docker 文档为准，这里用占位符表示 docker pull pyrosetta-docker-example docker run --rm -it pyrosetta-docker-example \ python -c "import pyrosetta; pyrosetta.init('-mute all'); print('docker ok')"容器里跑 PyRosetta 的好处是宿主机上的乱七八糟依赖完全影响不到它，坏处是每次挂载数据目录、传授权信息都要多几步配置。如果只是想在 Windows 上先试几段教程代码，Docker 是最快的；准备长期做项目，我建议 WSL2 里照 Linux 的 conda 流程装，省掉容器路径映射的反复折腾。
3. 用 conda 装 PyRosetta：从拿到许可证到 init 成功的完整命令
3.1 先拿到访问凭证：申请学术许可证并理解使用边界
PyRosetta 的学术许可证是免费的，但必须通过官方申请流程获取，流程会给你一对用户名和密码，后续 conda 通道校验靠的就是它。申请时按真实用途填写，非学术场景要购买商业授权。审核会有一定周期，所以第一步不是敲命令，而是先把账号申请下来，等邮件确认后再进入安装步骤。
拿到账号后要理解它的使用边界：学术许可证绑定的是注册人本人和当前用途，不能拿去给商业团队做内部工具，也不能在产线上对外提供服务。我见过有人把这套账号直接写进公司的公共 CI 脚本，最后被识别到违规调用，整个频道的访问被封掉，只能换联系方式重新申请，很折腾。正规做法是账号只存在个人或固定的账号管理者手里，团队分发时用官方提供的批量授权流程。
3.2 创建独立 conda 环境并配置 PyRosetta 官方通道
这是整个安装过程中最不容易出错、也最值得认真做的一步。先建环境，再配通道，官方通道需要认证，所以不能用conda install -c这种临时指定方式，正确做法是把通道持久化加到配置里：
# 1. 创建独立环境，python 版本以官方当前支持列表为准 conda create -n pyrosetta python=3.9 -y # 2. 激活环境 conda activate pyrosetta # 3. 把 PyRosetta 官方 conda 通道加入配置 conda config --add channels https://conda.pyrosetta.org # 4. 设置通道优先级为严格模式，避免依赖从其它通道混入 conda config --set channel_priority strict这里解释一下每条命令的作用：conda create -n pyrosetta python=3.9建立名为 pyrosetta 的独立环境，Python 版本按官方当前的声明选择，装完不会污染其他项目；conda config --add channels把官方通道加进配置，随后安装会自动走认证逻辑；channel_priority strict是很多人忽略的参数，它让 conda 严格从高优先级通道解析依赖，防止 PyRosetta 的依赖从 conda-forge 或 defaults 混进不同版本导致运行时符号缺失。
3.3 安装命令、版本标签与依赖解析
环境就绪后执行安装，conda 会提示输入之前申请到的用户名和密码：
# 安装默认 stable 标签 conda install pyrosetta -y如果不想用默认的 stable，可以显式指定标签：
# 安装 update 标签，适合需要新特性但希望相对稳定的场景 conda install pyrosetta=update -y # 查看当前环境中已安装的 pyrosetta 版本与构建号 conda list | grep pyrosetta安装时 conda 会做依赖解析，核心依赖包括 numpy、protobuf、python 等。pyrosetta=update里的update是版本标签而非版本号，这是 PyRosetta 通道特有的约定，别把它当成写死的数字版本；conda list | grep pyrosetta用来确认是否真的装上了，也能看到构建号，后续排查版本相关问题时这份输出是重要依据。
我一般会等Solving environment阶段跑完再离开终端，因为这一步经常卡在依赖回溯上，特别是网络状况不好时，看起来像“死机”，其实它只是没耐心等。如果这一步超过 10 分钟，直接 Ctrl+C 中断，换网络环境重试或参考第 5 章的排查方案。
3.4 第一次启动：init 的静音参数与数据库加载
装完不等于能用，import pyrosetta只负责把 Python 包加载进来，真正把底层 Rosetta 初始化起来的函数是init()。第一次调用init()会加载残基类型集、打分函数能量表、数据库索引，这个过程在机械硬盘上可能得等几十秒，容易让人误以为卡死。先跑一个最小启动：
# 第一次启动验证 import pyrosetta # -mute all 关闭所有 C++ 层级的日志输出，只留 Python 这边的展示 pyrosetta.init("-mute all") print("PyRosetta version:", pyrosetta.PyRosettaVersion()) print("Database path:", pyrosetta.database())-mute all是第一个值得记住的参数，PyRosetta 底层是 C++ 写的，默认会刷几十行数据库加载日志，加上它之后终端立刻清爽；pyrosetta.PyRosettaVersion()返回当前构建版本字符串，能用来和官方发布说明对照；pyrosetta.database()返回数据库目录的绝对路径，后面自定义数据库或排查加载问题时都要靠它。
如果这一步没有报错，说明核心安装是成功的。若在init()阶段出现段错误或找不到共享库，基本可以判断是依赖或者平台架构问题，进入第 5 章对号入座。
4. 验证安装是否可用：用测试集和最小打分协议说话
4.1 用官方自带的测试集做一次整体自检
安装完成后的第一件事不是写业务脚本，而是让官方测试集替你跑一遍整体环境。PyRosetta 安装包内自带测试目录，位置可以通过 Python 动态获取，不用凭记忆去翻 site-packages 路径：
# 打印测试目录的绝对路径 python -c "import pyrosetta, os; print(os.path.join(os.path.dirname(pyrosetta.__file__), 'tests'))"拿到路径之后，用 pytest 指向该目录执行：
# 先补齐 pytest，再用 -q 静默输出只保留失败摘要 pip install pytest python -m pytest <上面命令打印的路径> -q这种动态定位测试目录的做法比写死路径可靠得多，因为不同版本、不同安装方式的包路径可能不一样。-q参数让每个用例只输出一行结果，失败时会把完整 traceback 打出来，跑完看 summary 里的 passed / failed 数量就能判断安装是否完整。测试集里覆盖了打分函数、残基类型、姿态操作这些核心模块，任何一类 C++ 层面的符号链接缺失都会在测试阶段暴露，省得后面在业务脚本里排查。
4.2 从氨基酸序列构造 pose 并计算打分：最小可运行协议
测试集通过之后，再跑一个比测试集更有“业务感”的最小协议：从字符串构造一条短肽，计算全原子打分函数的总分。这段代码是 PyRosetta 入门教程里最常见的起手式，用来验证整条数据链路是否真的通畅：
from pyrosetta import * # 初始化并用 -mute all 屏蔽 C++ 日志 init("-mute all") # 从氨基酸序列构造 pose，20 个标准氨基酸足够覆盖残基类型表 pose = pose_from_sequence("ACDEFGHIKAAA") # 获取默认全原子打分函数 sfxn = get_fa_scorefxn() # 打印总打分值 print("total score:", sfxn(pose))pose_from_sequence是最常用的构造函数，它把字母序列翻译成包含坐标、侧链、原子类型的 Pose 对象，这个过程会校验每个字母对应的残基类型是否存在于数据库；get_fa_scorefxn()返回当前版本默认的全原子打分函数，内部含范德华力、氢键、溶剂化等能量项；sfxn(pose)的调用方式是对 Pose 做一次完整能量计算，最终值不需要有物理单位，它的意义在于验证打分函数已经从数据库里正确加载了能量表。如果这段代码能打印出一个数值，说明打分能量表、残基类型定义、坐标生成三项核心机制全部正常，安装已经足够支撑绝大多数入门实验。
4.3 数据库路径与并行参数的确认
PyRosetta 的数据库是随安装包一起分发的，里面包含能量参数、残基拓扑、片段库索引等文件。绝大多数情况下数据库路径由包内部自动定位，不需要手工设置环境变量，但确认它的实际位置仍然有意义，尤其是后面要自定义残基类型或换数据库版本时：
# 查看当前生效的数据库路径 python -c "import pyrosetta; pyrosetta.init('-mute all'); print(pyrosetta.database())"如果命令行输出路径落在 conda 环境的 site-packages 目录内，说明数据库被封装在 Python 包里，走的是标准安装流程。后续跑大规模计算时，还可以在init()阶段传入多线程参数：
import pyrosetta # 为交互图计算分配 4 个线程，适合打分函数计算密集的协议 pyrosetta.init("-multithreading:interaction_graph_thread_count 4 -mute all")interaction_graph_thread_count控制打分函数内部交互图计算的并行度，默认是 1，改成 4 在多核机器上会明显缩短打分耗时；-mute all与线程参数用空格分隔在同一条字符串里，这是 Rosetta 命令行参数的标准写法。注意init()在同一个 Python 进程里只能调用一次，想改参数必须重启解释器，这是很多人刚接触时容易踩的暗坑。
5. PyRosetta 安装避坑清单：五条真实的踩坑记录
5.1 装完之后 import 报错找不到 GLIBCXX 符号
现象：import pyrosetta成功，但init()时抛ImportError: ... /libstdc++.so.6: version 'GLIBCXX_3.4.x' not found，或者直接段错误。
原因：系统自带的 libstdc++ 版本低于 PyRosetta 二进制所需的版本。PyRosetta 的底层是 C++ 代码，编译时用了较新的 GCC 特性，运行时需要对应版本的动态库，而 conda 环境里的 libstdcxx-ng 没有被正确激活。另一个常见诱因是用户设置了LD_LIBRARY_PATH，把系统目录的旧库注入到了 Python 进程里，覆盖了 conda 环境自带的库。
解决：先在这个环境里补装更新的 libstdcxx-ng，然后检查/lib64/libstdc++.so.6是否被 LD_LIBRARY_PATH 强插进来：
conda install libstdcxx-ng -y unset LD_LIBRARY_PATHunset LD_LIBRARY_PATH是排查时最直接的验证手段，如果清空后不再报错，就去~/.bashrc里删掉对应的导出语句。注意不要手动替换系统级/usr/lib64/libstdc++.so.6，那属于操作系统包管理器的地盘，手改容易把其他依赖它的软件弄坏。
5.2 conda 安装时提示认证失败或 403
现象：conda install pyrosetta执行到下载阶段，报CondaHTTPError: 403 FORBIDDEN或InsecureRequestWarning然后中断。
原因：许可证账号密码错误，或者申请审核还没通过。PyRosetta 的 conda 通道在服务端做了权限校验，账号未激活、密码大小写错误、申请类型不一致都会直接拒掉请求。还有一种情况是使用-c参数临时指定通道，conda 不会弹出交互式输入框，导致匿名访问被拒。
解决：先确认申请邮箱收到审核通过邮件，再重新配置通道并执行安装。重点检查密码里容易混淆的大小写和特殊字符，不要复制带首尾空格的内容。
# 移除旧通道重新添加，触发交互式认证 conda config --remove channels https://conda.pyrosetta.org conda config --add channels https://conda.pyrosetta.org conda install pyrosetta -y5.3 conda 在 Solving environment 阶段卡住不动
现象：敲完安装命令后，终端停在Solving environment超过 10 分钟，CPU 占用却很低。
原因：conda 的依赖解析器在做回溯时遇到了大量候选版本组合，尤其是默认通道和 PyRosetta 官方通道里的依赖版本差异较大时，复杂度会爆炸式上升。网络响应慢也会让求解进程长时间挂起，看起来像死机。
解决：先 Ctrl+C 中断，改成严格通道优先级后再装：
conda config --set channel_priority strict conda install pyrosetta -y如果依然慢，就换一个时段再试，或者在网络状况更好的机器上装完，再用第 6 章的离线方案移植。别硬等，我见过在 Solving environment 上干等一个小时的案例，最后发现是网络丢包导致依赖元数据反复拉取。
5.4 把 PyRosetta 装进 base 环境后，原有深度学习环境崩了
现象：原本跑得好好的 PyTorch 项目，在装完 PyRosetta 之后突然报numpy.ndarray size changed或protobuf runtime mismatch，重装 numpy 后另一边又崩。
原因：PyRosetta 的依赖解析把环境里的 numpy、protobuf 升级到了它要求的版本，覆盖了深度学习框架原本兼容的版本区间。conda 的求解器认为“升级依赖”是合理操作，但不会提醒你这个升级会破坏其他包。
解决：回到第 3 章的规范流程，PyRosetta 永远装在独立环境里。如果已经污染了原环境，没有精确回滚办法，最省事的是conda create一个新环境重装原有项目，这也是我反复强调环境隔离的原因。依赖被破坏之后追悔莫及，记住这条教训比任何修复命令都值钱。
5.5 网上旧教程代码在新版本上跑不通
现象：照着一篇几年前的教程写pose_from_sequence或某个 mover 的调用，报AttributeError: module 'pyrosetta' has no attribute 'xxx'，或者 API 参数个数不匹配。
原因：PyRosetta 的 Python API 随版本持续调整，旧教程对应的是当时的分发方式，现在的init()签名、mover 的命名空间、分布式模块的导入路径都和过去不同。尤其是pyrosetta.distributed这一块，改动频率很高。
解决：以官方仓库当前年份的 test 目录和教程为本，先跑通官方测试集再改自己的脚本。安装时优先选stable标签，不要用rolling来做生产课程或正式实验，否则今天能跑的代码下个月可能就不兼容了。遇到AttributeError时，用dir(pyrosetta)查看当前环境里真实存在的符号名，比翻旧文档更快。
6. 更进一步：离线环境与大集群上的 PyRosetta 实用部署技巧
如果目标机器没有外网，或者需要在多个节点上重复安装，conda 的在线安装流程就不适用了。常见做法是找一台有网的机器装好环境，用 conda 自带的导出功能把环境清单固定下来，再用打包工具把整个环境迁移过去。第一步先导出一份完整的 yaml 描述文件：
# 导出当前环境的所有包和版本约束 conda env export -n pyrosetta > pyrosetta_env.yaml导出的 yaml 会包含通道地址、构建号和操作系统标识，离线机器上可以用它重建环境。但 yaml 方式要求离线机器能访问同一通道，如果不满足，退一步用conda-pack这类工具直接打包整个环境目录，拷贝到目标机器解压后激活即可使用。打包迁移前，注意源机器和目标机器的操作系统发行版尽量一致，跨大版本移植容易遇到 glibc 兼容问题，这个坑在集群场景里比在线安装时更隐蔽。
还有一个集群场景值得提醒：多节点共享同一份 PyRosetta 安装目录虽然省磁盘，但第一次init()时每个节点都要读取数据库文件，共享文件系统在并发读取时可能出现锁等待或性能骤降。我现在的习惯是每个计算节点各装一份，数据库路径用本地 SSD，日志从-mute all改成-mute core，保留核心错误输出又不会日志刷屏：
import pyrosetta # 集群环境下的 init 参数：保留核心报错，关掉冗余日志 pyrosetta.init("-mute core -multithreading:interaction_graph_thread_count 4")这套组合在本地开发、容器部署、离线迁移三种场景下我都验证过，核心原则只有一个：把 PyRosetta 当成一个带许可证的独立运行时，而不是普通的 Python 包。给它独立环境、固定版本、干净的运行目录，它就很少再给你添乱。希望帮到你。
本文还有配套的精品资源，点击获取
