简介这是一份针对Pyrosetta安装的简明实战指南面向生物信息学研究者、计算化学开发者以及需要在Python环境中调用Rosetta进行蛋白质结构预测、分子对接和蛋白质设计的用户。资源以conda安装为主线清晰列出官方推荐的安装命令并针对默认源速度慢、下载中断或依赖冲突等实际场景提供了多个可选镜像源地址与切换方法同时覆盖安装后的import验证技巧以及网络连接、版本兼容、系统依赖等典型报错的排查思路可有效减少环境配置环节的摸索时间。压缩包内共包含3个文件以可运行的inscode脚本、HTML说明页面和gitignore配置文件为主整体大小仅4KB轻量而聚焦。内容按安装流程组织步骤指令与说明文字对应清晰读者可对照执行、按需检索。目前已有112人学习浏览尤其适合准备快速上手Pyrosetta的科研新手和希望规避安装陷阱的开发者。1. PyRosetta 安装指南最难的不是 pip而是许可与分发的三重门PyRosetta 是蛋白质建模套件 Rosetta 的 Python 绑定几乎是结构生物学、蛋白质设计和计算酶学入门绕不开的第一道坎。我在某课题组给新成员配环境时发现一个规律第一次装 PyRosetta 的人十有八九不是倒在代码上而是倒在许可文件、conda 渠道和平台匹配这三件事上。装好之后import pyrosetta; pyrosetta.init()两行就能跑但这两行背后是一个大型 C 编译产物、一个许可校验和一大套科学计算依赖在撑着。这篇文章按我实际配环境的顺序来写先讲清楚它为什么不能像普通包一样一把梭安装再给三条安装路线和各自的取舍最后把高频报错逐条拆开。适合刚拿到学术许可、准备在本地搭蛋白质建模环境的人已经装过的同学可以直接跳到第 5 章对照排查那里集中了我这几年踩过的坑。2. 装 PyRosetta 之前先看懂它的构建方式与三种分发形态2.1 为什么 PyRosetta 不在 PyPI 上绑定层与核心库的关系PyRosetta 不是独立软件而是给 Rosetta C 核心库套了一层 Python 绑定。Rosetta 核心有数十万行 C模板和表达式模板用得极多全量编译一次要几小时到十几小时产物里还要带上完整的数据库目录——打分函数参数、旋转异构体库、侧链能量表都在里面。这决定了 PyRosetta 的分发只能走预编译大包这条路要么拿编译好的 conda 包或 wheel要么自己从头编译。PyPI 上没有它一是包体量太大且携带非纯 Python 二进制二是它的许可体系不允许匿名自由下载。理解这一点你就能接受后面所有麻烦它不是一个pip install pyrosetta就能结束的普通依赖。绑定层本身是用 pybind11 之类工具生成的每出一个 Rosetta 大版本绑定代码都要重新生成并针对目标平台编译。官方通常只维护少数几个主流平台和 Python 版本的构建产物这就是为什么你拿到手里的是发布页 授权回执而不是一个公共索引地址。另一个容易忽略的点是PyRosetta 的 wheel 和 conda 包体积动辄几百 MB 到 1GB 以上下载慢、磁盘占用大是常态不是你的网络或者镜像源出了问题。装之前先给自己打个预防针后面见到大文件就不会慌。2.2 三条安装路线怎么选conda、wheel、源码自编译路线适合场景时间成本上手难度conda 官方渠道绝大多数人想快速跑通全套依赖10-20 分钟低下载 wheel 后用 pip 装已有环境不便加 conda 渠道或要锁定特定版本5-10 分钟低源码自编译要改 C 核心、官方没覆盖你的平台、定制编译选项数小时起步高我一般默认推荐 conda 路线因为 PyRosetta 对依赖的版本很挑剔conda 的解析器会把 numpy、scipy 这些科学栈一起按兼容版本装好省去大量手工对齐。wheel 路线适合内网离线环境、或者你所在的集群不能随便新增 conda 渠道的场合缺点是它只管自己这个包依赖你得自己配。源码自编译我只建议两类人碰一类是要改 Rosetta C 代码甚至改绑定层的人另一类是平台冷门到官方没出构建包的人。如果你只是跑打分、做 relax、跑 folding千万别从源码开始那是在用写论文的时间换环境配置的满足感。2.3 平台与 Python 版本先对号入座再动手PyRosetta 的官方构建通常覆盖 Linux x86_64 和 macOSmacOS 上会区分 Intel 与 Apple Silicon 两套产物Apple Silicon 机型别下错架构。Windows 原生没有官方构建官方推荐路线是 WSL2 里装 Ubuntu 再走 Linux 包或者用容器镜像跑。每年都有同学在 Windows 原生环境里耗掉一整天最后发现方向就错了——这一步先确认平台能省掉后面所有玄学问题。Python 版本方面发布页一般会标注支持区间过去几个大版本常见覆盖范围在 3.8 到 3.11 一带具体以你下载到的发布说明为准。装之前先跑python --version确认解释器版本再跑conda info看环境归属避免装完才发现建环境的 Python 根本不在支持区间里。这一步 30 秒能帮你躲过一个下午。3. conda 路线落地从建环境到 init() 跑通全流程3.1 先建一个干净的 conda 环境别直接装进 baseconda create -n pyrose python3.10 -y conda activate pyrose python -c import sys; print(sys.version_info[:2])逻辑说明建独立环境的核心原因在于 PyRosetta 的 C 绑定层在编译期就定死了 ABI对 numpy、scipy 这类科学计算库的版本非常敏感。装进 base 环境很容易和系统自带的包、其他项目的依赖打架一旦冲突报错信息会指向你完全想不到的地方。第三行的python -c是为了确认你激活环境后当前解释器确实是刚建的 pyrose很多装完 import 失败的案例根因都是 conda 环境没激活pip 装到了另一个 Python 里。参数说明python3.10是一个相对稳妥的选择但如果你要装的 PyRosetta 发布版只支持 3.9就换成 3.9总之以发布页标注为准。-n pyrose是环境名可以随便起但建议起短一点后面每条命令都要带着它。-y表示跳过安装确认批量脚本里必加交互环境里不加也行。3.2 添加官方 conda 渠道并安装渠道地址只认官方回执conda install -c CHANNEL_ADDR pyrosettaconda search -c CHANNEL_ADDR pyrosetta逻辑说明这里的 CHANNEL_ADDR 是一个占位符实际地址要从你提交学术许可申请之后官方回执里的安装说明中复制。不要从网上老教程里抄渠道地址我见过不止一次因为渠道换过地址、旧链接装出来版本老旧或被直接拒绝访问的情况。安装前先跑一遍conda search把渠道里当前可用的版本列出来这一步能同时确认两件事渠道地址没写错、你想要的版本确实在里面。如果 search 都搜不到就别继续装先回头检查渠道地址。参数说明-c是临时把某个渠道加入本条命令的搜索优先级不会永久写入.condarc配置文件。官方渠道通常会在安装时自动解析 numpy 等依赖的兼容版本所以你会发现它不只是装一个包而是一起装一小串科学计算栈这是正常的别中断。如果你希望以后每次conda install pyrosetta都能直接命中可以把这个渠道写进 condarc但我不建议默认这么做——会带来第 5 章要讲的频道污染问题。3.3 放置许可文件并完成 init() 首次验证mkdir -p ~/.rosetta # 将官方回执附件中的许可文件放入该目录或按邮件说明通过环境变量指定路径 export ROSETTA_LICENSE/your/path/to/licenseimport pyrosetta pyrosetta.init(-mute all) print(PyRosetta init OK)逻辑说明pyrosetta.init()是每个 PyRosetta 脚本的必经入口它负责读许可、加载打分函数、初始化命令行选项系统相当于把整个 Rosetta 引擎在 Python 进程里拉起来。许可文件放哪里、叫什么名字以官方回执说明为准但常见做法是放进家目录下的隐藏目录或者通过环境变量指向文件位置。这里有个很隐蔽的坑如果你用 export 指定环境变量必须在同一个 shell 会话里运行 Python环境变量不会跨会话保留。我习惯顺手把 export 写进 shell 配置文件省得每次重开终端都报找不到许可。参数说明-mute all会把启动阶段的大量日志关掉只保留错误输出适合验证安装时使用。但新手调试阶段我建议先不要加这个参数完整跑一遍日志你能看到 Rosetta 到底加载了哪些数据库文件和参数表对后续排查问题非常有帮助。init 跑通的标准是看到PyRosetta init OK且进程正常退出如果这里报错直接跳到第 5 章对号入座。4. 不只有 condawheel 安装与源码自编译的适用场景4.1 wheel 路线在已有环境里用 pip 装本地包pip install ./PyRosetta-版本-Python版本-平台.whlpip install numpy2 # 只有碰到版本不兼容报错时才需要锁版本逻辑说明wheel 路线的本质是跳过 conda 的依赖解析直接把绑定层装进现有环境。适用场景很明确目标机器访问不了 conda 渠道内网、离线集群或者你要和团队锁定同一个 PyRosetta 版本。从下载页拿 wheel 文件时页面会让你勾选 Python 版本和操作系统这一步就决定了你选哪个文件。文件名里的三要素——版本、Python 版本、平台——必须和你的环境完全对得上装完立刻python -c import pyrosetta验证别等写完整个脚本才发现问题。参数说明numpy2这条是我加了注释的预防性命令不一定用得上。PyRosetta 这类带编译后二进制的包对 numpy 大版本升级非常敏感某段时间 numpy 主版本跳升后老 wheel 在 init 阶段直接报 undefined symbol行业里普遍做法是把 numpy 固定回 1.x。判断标准很简单如果 import 和 init 都正常就别动 numpy只有报符号错误时才去锁版本。另外pip 安装时如果提示要升级或降级一堆依赖建议加--no-deps先装本体再手动补齐缺的依赖避免 pip 擅自改动你环境里其他包。4.2 源码自编译给改 C 的人不是给赶论文的人# 以官方源码构建脚本为例实际脚本名以你拿到的源码说明为准 ./build_pyrosetta.sh --python-executable $(which python) --compiler gcc --mode release -j 4逻辑说明源码编译适合三类人官方包没覆盖你的平台、你要改 Rosetta C 核心代码、你需要自定义编译选项。编译前要装齐工具链Linux 上通常是 cmake、g 和 Python 开发头文件头文件缺失的典型报错是找不到 Python.h。磁盘空间建议留 30GB 以上编译产物加上数据库比你想的大得多。整机编译一次几个小时起步第一次跑我建议用-j 4而不是更高并行度编译是内存密集型任务并行度过高容易把机器拖死轻则 OOM 中断重则整机卡死。关键参数说三个--python-executable一定要指向你要用的那个 Python最常见翻车就是这里指向了系统 Python编出来的模块 import 时版本对不上--mode release是发布模式debug 模式编译更慢且运行时更卡非调试场景不要选-j是并行编译任务数虚拟机或内存小于 16GB 的机器保守用 2 到 4。编译完成后生成的包在 build 目录下使用时要把它加进PYTHONPATH这一步官方构建脚本一般会提示别忽略。4.3 三条路线的选择顺序别把时间花在迁移上我的建议是严格按这个顺序试先 conda不行再 wheel最后才源码。原因很简单conda 路线依赖解析最省心wheel 路线最灵活源码路线全是坑但覆盖所有定制需求。这里有一个血泪经验不要先跑通 conda 版本过了两天又因为想改 C 而切到源码编译然后发现写好的脚本依赖的包在编译版里没编译进去白白浪费一个周末。动手前先问自己一个问题——你要用 PyRosetta 跑现成的打分和 relax还是要动它的 C 内核答案在前者老老实实用 conda 或 wheel答案在后者直接从源码开始别走弯路。5. PyRosetta 安装常见问题排查五个高频坑与对应解法5.1 import 成功但 init() 报 license 错误现象import pyrosetta正常但运行pyrosetta.init()时提示找不到许可文件或文件无效程序直接退出。原因许可文件没有放到 init() 默认查找的位置或者环境变量指向的路径不对。最常见的是放到了错误的目录层级或者文件名与发布说明里标注的不一致。解决先确认官方回执里给出的放置路径约定常见做法是放在家目录下的隐藏目录如果用环境变量指定路径检查 export 是否写进了当前 shell 或 shell 配置文件。改完之后不要立刻重跑先echo $ROSETTA_LICENSE确认真实生效。5.2 init() 时报 undefined symbol 或模块加载失败现象init 过程中抛出 undefined symbol 错误或者 import 阶段就报错指向某个 numpy 相关符号。原因环境里的 numpy 版本与 PyRosetta 编译时使用的版本 ABI 不兼容大版本升级后尤其明显。解决固定 numpy 大版本常见做法是装回 1.x 系列改完创建全新环境重装 PyRosetta会比在旧环境里反复降级更省时间。注意 conda 环境下不要混用 pip 和 conda 操作同一个包这是 ABI 冲突的另一大来源。5.3 init() 正常但一加载蛋白就内存暴涨、进程被杀现象init 没问题但pose_from_pdb加载稍大的结构时内存飙升甚至 OOM 被系统杀掉。原因PyRosetta 加载结构时会构建完整 pose 内部表示加上打分函数初始化占用的内存某些机器配置下确实吃紧另一个常见原因是 PDB 文件本身带了很多异常残基或水分子。解决先用小结构验证环境是否正常比如一个几百残基的蛋白确认正常后再处理大目标。脚本里建议在 init 阶段用-mute all减少日志缓冲同时确认系统 swap 是否开启。如果每次都在固定位置崩检查 PDB 文件是否来自非标准来源常见做法是先用工具清洗再读入。5.4 conda 里装了 MPI 版后 import 失败或运行不了现象安装了标注 mpi 的 PyRosetta 包普通python直接跑脚本报错或者提示无法启动运行时环境。原因MPI 版需要配合 mpich 或 openmpi 使用并且要通过mpirun启动脚本直接python跑不符合它的运行方式。解决确认你装的是不是 MPI 版如果不是明确需要多进程并行采样就换普通版。如果必须用 MPI 版先确认 MPI 实现已安装然后用mpirun -np 4 python your_script.py方式运行不要试图在普通 Python 解释器里启动多进程。5.5 Windows 上装完永远跑不起来现象在 Windows 原生环境里按各种教程折腾conda 装上了import 也过了但 init 崩溃或行为异常。原因PyRosetta 没有官方 Windows 原生构建你装到的多半是兼容层转出来的包数据库路径和系统调用都存在隐患。解决直接在 Windows 上装 WSL2在 WSL2 的 Ubuntu 里重走第 3 章流程或者使用官方容器镜像把代码和数据挂载进去跑。别在原生 Windows 环境里继续调试我亲眼见过同学在这个坑里耗了两个通宵最后切到 WSL2 半小时跑通。6. 安装收尾的最后一个动作跑通一个最小结构任务安装验证不能停在 init我建议每个新环境都跑一遍下面这个最小流程读入一个 PDB、算一次打分、做一次快速 relax、输出结果文件。这套流程能覆盖 init、pose 构建、打分函数、协议运行、IO 输出五个关键环节全部通过才算这个环境真正可用。import pyrosetta pyrosetta.init(-mute all) # 读入一个小蛋白结构替换成你手边的 PDB 文件 pose pyrosetta.pose_from_pdb(demo.pdb) # ref2015 是全原子打分函数常用于可溶性蛋白建模 sfxn pyrosetta.create_score_function(ref2015) print(raw score: %.2f % sfxn(pose)) # FastRelax 是结构优化最常用的协议之一 from pyrosetta.rosetta.protocols.relax import FastRelax fr FastRelax() fr.set_scorefxn(sfxn) fr.apply(pose) print(relaxed score: %.2f % sfxn(pose)) # 输出优化后的结构 pyrosetta.dump_pdb(pose, relaxed.pdb)逻辑说明create_score_function(ref2015)创建全原子打分函数raw score是输入结构的初始能量FastRelax会对结构做迭代优化正常情况下 relax 后的分数应该比初始分数低这本身就是对安装正确性的一次检验。dump_pdb如果没用过可能不知道它是直接落在当前工作目录的建议先确认工作目录再跑省得找输出文件。参数说明-mute all在这里保留因为验证阶段我们只关心分数结果不关心每次迭代的细节日志如果你想观察 relax 过程把这行改成-mute basic或直接去掉。demo.pdb建议先用小结构几百个残基的蛋白一分钟内能跑完如果直接上大复合物FastRelax 可能要跑很久这不该归咎于安装。关于 relax 的随机性有两点经验同一输入多次运行分数会有微小浮动这是采样过程的正常现象不是环境问题如果想复现结果可以在 init 里加随机种子参数。验证通过后这个环境就可以放心投入日常使用了。最后说一句我的习惯每次给新机器装完我都会把第 5 章的排查清单和这个最小验证脚本存成一个文件放在项目目录里下次哪个环境出问题直接对照跑一遍五分钟定位问题。这套流程陪我配过几十台机器被它救过的次数远比我承认的多希望这一篇能帮你在 PyRosetta 安装这条路上少走点弯路。本文还有配套的精品资源点击获取