简介面向需要在Python环境中使用Rosetta功能的蛋白质研究者与生物信息学工程师这份Pyrosetta安装指南以代码包形式提供完整、可对照操作的安装方案。内容围绕conda安装命令、镜像源切换和导入验证展开并附有安装过程中网络连接、版本兼容、系统依赖等常见错误的排查思路能帮助用户避开坑点、顺利完成环境配置。资源包共3个文件以HTML说明文档为主配合inscode脚本与gitignore配置整体仅4KB结构精简适合快速查阅。已有107人学习下载对于初次接触Pyrosetta、希望高效搭建蛋白质结构预测与分子对接实验环境的读者是一份实用的上手参考。 开头先交代个背景我最早接触PyRosetta是在两年前实验室要做蛋白质结构设计想用Rosetta的Python绑定写脚本。当时我对这套工具的印象就是装起来很麻烦结果真的动手装卡了整整三天。不是这个包本身有多神秘而是它对Python版本、许可证、系统环境的绑定非常苛刻任何一个环节没对上import pyrosetta那一步就会掉链子。这篇安装指南就是把我后来重装、给学生排错过程中的所有关键点整理出来从环境准备到踩坑排查尽量让你一次装通。如果你是做计算生物学、蛋白质结构预测或设计方向的研究生或者单纯想跑一下Rosetta的Python示例代码这篇文章都适用。我尽量不只会贴命令还会解释为什么这么操作——毕竟PyRosetta的安装问题多数不是命令执行错而是没理解它的版本和依赖逻辑。1. 装PyRosetta之前的认知准备版本关系、许可证与系统环境1.1 PyRosetta不是普通PyPI包很多人第一次装PyRosetta下意识就是pip install pyrosetta一把梭。这种习惯在装普通库时没问题但在PyRosetta这里不够用。它是Rosetta C核心库的Python绑定本质上是把一整个巨大的C二进制包装成了Python模块。这意味着三件事它和Rosetta的大版本强绑定不同Rosetta版本对应不同的PyRosetta构建API行为也有差异。它对Python解释器的版本有严格限制不是写在requirements里让你自动装个副本那么简单而是必须在编译时绑定了特定的Python ABI。它的二进制体量很大动辄几百MB到上GB依赖的底层库numpy、scipy、boost、hdf5等都是编译期固定版本普通pip在解析依赖时容易把环境搞乱。所以安装PyRosetta的第一步不是找安装命令而是明确你需要的版本形态。当前新版的包名通常就叫pyrosetta而旧版包名类似PyRosetta4.Release两者在安装方式上有所区别。从2022年前后开始官方逐渐过渡到conda分发这也是我推荐的路径。1.2 许可证学术免费但必须主动申请另一个常被忽略的点是许可证。PyRosetta不是完全开源的自由软件它要求使用者注册账号并申请学术License。学术用途可以免费但商业用途需要单独购买。许可证本身的申请流程不复杂到PyRosetta官网注册、填写单位信息、等待邮件发放license文件。但安装阶段实际影响你的是这个文件放哪、怎么让PyRosetta找到它。常见的做法有两种把license文件放在用户主目录下PyRosetta默认会扫描常见路径。显式设置环境变量ROSETTA_LICENSE指向license文件路径。我建议直接用环境变量路径清晰排查问题也方便。在我自己写脚本的机器上我习惯添加到~/.bashrc或~/.zshrc里export ROSETTA_LICENSE/path/to/your/license申请下来的license文件通常有有效期过期之后pyrosetta.init()会报错这个后面讲排查时会专门提。1.3 系统选型Linux优先Windows走WSL如果你用的是Windows我真心建议不要直接在原生Windows环境里折腾。PyRosetta的官方预编译包主要面向Linux和macOSWindows版本偶尔有一些但经常落后于主版本而且动态库依赖问题会把你折磨到怀疑人生。最好的方案是Windows上装WSL2在Ubuntu里跑。我试过直接用Windows版PyRosetta做模拟踩过一堆坑后来切到WSL2之后问题少了一大半。系统版本方面Ubuntu 20.04、22.04这类主流LTS版本支持最好。macOS方面Intel芯片的兼容性更稳一些Apple Silicon近两年也有构建但要注意Python版本需要是原生的arm64版本不要混用x86_64的Python。还有一个容易被忽略的系统级依赖glibc版本。PyRosetta的二进制对glibc有最低版本要求如果你的系统太老比如某些CentOS 7老机器可能装完之后import就挂。可以先跑一下ldd --version看看glibc版本太旧的话建议换系统或升级容器。2. 环境隔离与依赖预检为什么我强烈建议用conda/mamba装2.1 创建专用环境PyRosetta安装最大的隐形杀手就是它和外部依赖的版本冲突。尤其是numpy、scipy这种计算栈核心库PyRosetta的二进制在编译时绑定了特定接口你如果把numpy升到太新的版本轻则警告重则segfault。所以我的第一条建议永远是用conda/mamba创建一个独立环境不要在base环境里直接装。conda create -n pyrosetta python3.10 conda activate pyrosettaPython用哪个版本以官方当前支持的版本为准2024年前后官方构建一般覆盖3.8到3.11这个区间。不要用太新的版本也不要选系统自带的老版本conda环境里指定一个稳定的即可。创建独立环境还有一个好处如果你同时做深度学习或传统分子模拟多个项目之间的依赖互相隔离不会因为一个项目升级库导致另一个项目宕机。2.2 预检系统依赖与磁盘空间创建环境后先做一次简单预检再进入安装步骤。我一般检查三个东西glibc版本ldd --version如果输出里显示2.27或更低建议先考虑升级系统或者使用官方提供的容器镜像。磁盘空间df -h .PyRosetta的包体量不小新版包下载和解压后可能占用好几GB建议预留10GB左右比较稳妥。我之前在服务器上遇到过磁盘满了导致解压失败的情况报错信息却很隐晦查了半天才发现是No space left on device。Python版本确认python --version确认当前环境的Python版本在官方支持范围内。多个Python环境并存时这一步特别重要因为which python指向哪里决定了你后面装的是哪个环境。2.3 用mamba替代conda提升解析速度如果你以前被conda慢到怀疑人生可以试试mamba。mamba是conda的C重写版依赖解析速度大幅提升用法几乎兼容conda install -c conda-forge mamba mamba create -n pyrosetta python3.10 mamba activate pyrosettaPyRosetta的依赖树比较大用mamba能在几秒内完成解析而conda可能要等两分钟甚至更久。实测下来装PyRosetta用mamba的体验会顺畅很多。3. 安装实操的三种路径详解conda、pip与源码编译3.1 路径怎么选我把可行的安装路径整理成了一张表方便你根据自己的场景选安装方式适合场景复杂度常见坑conda/mamba安装大多数用户的首选低渠道配置错误、许可证路径pip安装wheel已有指定版本需求时中Python版本不匹配、依赖冲突源码编译需要深度定制或新功能极高编译依赖缺失、耗时非常长除非你确实需要改动Rosetta底层C代码否则不要选源码编译。编译一次耗时长不说还会遇到boost、scons、平台库的一堆问题费这个时间不如直接等官方构建。3.2 推荐路径conda直接安装conda安装的核心是添加RosettaCommons官方渠道。操作步骤conda config --add channels https://conda.rosettacommons.org conda config --add channels conda-forge conda create -n pyrosetta python3.10 conda activate pyrosetta conda install -c https://conda.rosettacommons.org pyrosetta这里有两个细节要注意官方渠道的URL是https://conda.rosettacommons.org不是rosetta频道。我在网上见过不少人写错导致找不到包。先后顺序有讲究。把RosettaCommons放在较前位置conda-forge放在后面目的是让依赖解析时优先使用官方构建的版本减少不同二进制混合的兼容性问题。执行完conda install后可以先简单验证一下包是否真的装上了conda list | grep pyrosetta能列出包名和版本说明安装阶段没出问题。接下来是许可证配置和init验证见第4节。3.3 备选路径pip安装wheel与旧版包某些情况下你可能没法用conda比如所在平台没有官方conda包或者你明确需要某个旧版本。这时可以考虑pip安装wheel。旧版PyRosetta通常从官网下载对应操作系统和Python版本的wheel包然后执行pip install /path/to/PyRosetta4.Release-xxx.whl新版也可以用pip install但需要留意PyPI上的包名和版本是否支持当前Python版本。pip安装虽然能完成但在依赖解析上比较粗放容易出现numpy版本被自动升级/降级的情况。我的建议是除非你已经熟悉PyRosetta的版本机制并且能处理依赖问题否则优先走conda。pip路径更适合那种公司内网离线环境只能下载好wheel包再手动装。4. 许可证配置与首次验证import不报错的完整判断标准4.1 License文件放置与环境变量安装完成后第一件事不是急着写代码而是确认PyRosetta能找到license。如果之前没有设置ROSETTA_LICENSE环境变量PyRosetta会扫描主目录等默认位置。为了让行为可预期我推荐显式设置export ROSETTA_LICENSE/your/license/path/pyrosetta_license.dat这里有个小经验license文件的路径里尽量不要包含中文或空格PyRosetta读取环境变量时对路径处理不算特别健壮我见过因为路径里有空格导致license读不到的案例。如果你已经把license放在~下可以用echo $ROSETTA_LICENSE确认是否已经设置。4.2 首次import与init接下来在命令行里跑python -c import pyrosetta; pyrosetta.init(-mute all)这个命令如果没有任何输出并正常退出说明安装和license配置已经成功了一大半。-mute all的作用是屏蔽Rosetta初始化时的日志输出。不要小看这个参数Rosetta初始化默认会打印一大堆信息在调试时很烦。如果你刚接触PyRosetta我建议在脚本里也统一加上这一句否则输出刷屏会影响你关注真正的报错信息。4.3 判断安装成功的完整标准很多人以为import pyrosetta不报错就算装好了其实不够。真正能说明问题的是pyrosetta.init()执行成功并且能完成一个简单的蛋白质建模操作。我一般测试这段import pyrosetta pyrosetta.init(-mute all) from pyrosetta import pose_from_sequence pose pose_from_sequence(TEST) print(pose.sequence())这段代码会从一段氨基酸序列构建一个简单的pose对象如果输出TEST说明PyRosetta核心功能正常。我还见过一种情况init能过但pose_from_sequence一跑就崩溃。这种大多是numpy等底层库版本不匹配可以尝试重装环境或用官方conda渠道重新解析依赖而不是继续用那个半残的环境。4.4 第一次运行常见的小问题第一次运行时你可能会遇到init提示找不到数据库路径。这是因为PyRosetta内部需要Rosetta数据库文件虽然官方包通常自带但如果某些环境变量被错误设置会导致数据库路径解析失败。解决办法是检查环境变量ROSETTA3_DB或PYROSETTA_DB是否被设置过如果设置过但指向不存在的目录直接unset即可unset ROSETTA3_DB unset PYROSETTA_DB然后再重新跑验证脚本。多数情况下让PyRosetta使用包内默认数据库路径就是最省心的选择。5. 典型报错的排查链路从ModuleNotFoundError到libssl崩溃5.1 ModuleNotFoundError先查哪个环境而不是装没装PyRosetta安装报错里最高频的是ModuleNotFoundError: No module named pyrosetta很多人的第一反应是没装好于是重装一遍又一遍。但真正原因常常是Python解释器环境不对。我建议的排查顺序是which python python --version pip list | grep pyrosetta conda list | grep pyrosetta先确认当前shell里的python到底是哪个环境的。如果你建了conda环境但忘记激活或者IDE里选择了解释器都会出现明明装了却找不到模块的情况。特别是用VSCode时终端激活了conda环境但Jupyter kernel用的还是系统Python这种情况超常见。正确激活环境后再跑验证脚本conda activate pyrosetta python -c import pyrosetta; pyrosetta.init(-mute all)5.2 ImportError动态库相关报错版本绑定问题在Linux上PyRosetta有时会报类似ImportError: libpython3.10.so.1.0: cannot open shared object file: No such file or directory这种报错说明当前Python解释器和PyRosetta二进制所绑定的Python ABI不一致。最常见的场景是conda环境里是Python 3.10但系统里还装了其他Python动态库搜索路径把旧版本库给找出来了。排查办法ldd $(python -c import pyrosetta; print(pyrosetta.__file__)) | grep not found把PyRosetta模块文件拿到ldd下检查看看哪个依赖库缺失。如果缺的是libpython基本可以确定是Python解释器版本不对切换到conda官方渠道重装环境就能解决。如果报错涉及libssl、libcrypto大概率是系统OpenSSL版本和PyRosetta依赖的动态库冲突。这种情况有一个讨巧的解决思路把环境的lib目录优先加入动态库搜索路径export LD_LIBRARY_PATH$CONDA_PREFIX/lib:$LD_LIBRARY_PATH但要注意这个方案只是临时绕过根治还是要确保依赖都来自conda渠道。5.3 init阶段License报错先分清过期和找不到pyrosetta.init()阶段最典型的报错是RuntimeError: Bad license或License not found这两个字面不同含义完全不同Bad licenselicense文件内容有问题通常是文件损坏、复制缺失字符、或者license已过期。License not foundPyRosetta根本没找到license文件要么ROSETTA_LICENSE没设置要么路径指向了不存在的文件。处理思路也很直接echo $ROSETTA_LICENSE ls -l /path/to/license head -n 5 /path/to/license确认文件存在且内容完整。如果申请license后等很久没收到邮件去官网后台重新申请或查看是否被归入垃圾邮件。5.4 初始化成功但运行崩溃先怀疑版本混用还有一种情况让我记忆犹新初始化完全正常但只要一跑能量计算就Segmentation fault。后来发现是conda环境里混入了系统pip装的numpy两个numpy版本ABI不兼容导致。排查方式python -c import numpy; print(numpy.__version__, numpy.__file__)确认numpy来自conda环境目录而不是/usr/lib/python3/dist-packages之类的地方。如果你之前用pip装过东西建议在这个专用环境里彻底禁用pip安装第三方库或者不要在执行前用pip upgrade numpy。5.5 离线/内网环境安装wheel包下载后手动装如果单位内网不能直接访问conda频道可以在有网的机器上先把PyRosetta及其依赖下载好conda create -n pyrosetta python3.10 --offline conda install -c https://conda.rosettacommons.org pyrosetta --download-only然后把pkgs目录打包拷贝到内网机器。虽然过程繁琐但比在内网里反复尝试连服务器要快得多。PyRosetta的依赖链很复杂不要试图手动一个个下载wheel用conda的--download-only能避免很多遗漏。6. 装好之后的第一个小工程IDE配置、并行计算与性能建议6.1 让Jupyter和VSCode正确指向conda环境安装成功往往只是开始写代码时还会遇到一个问题IDE里找不到pyrosetta。如果你用Jupyter需要先在conda环境里安装ipykernelconda install ipykernel python -m ipykernel install --user --name pyrosetta --display-name Python (pyrosetta)然后在Jupyter里切换kernel到Python (pyrosetta)这样就能在notebook里正常import pyrosetta。VSCode用户在写代码前用CtrlShiftP搜索Python: Select Interpreter选择conda环境里那个Python路径。小坑是有时候VSCode会自动选中全局Python导致import pyrosetta报错但终端明明能跑通。重新选中解释器就行。6.2 并行计算多线程和多进程的取舍PyRosetta默认是单线程的计算密集的折叠模拟会比较慢。官方提供支持MPI的版本但安装复杂度更高如果只是做中小规模蛋白的序列设计或结构预测单线程往往够用。如果你要在脚本里做多组独立模拟最稳妥的方式是用Python的multiprocessing每个进程独立pyrosetta.init()。注意不要在每个进程里反复调用init()次数过多最好在worker初始化时只调用一次。另外PyRosetta内部偶尔会用到OpenMP如果在多进程场景下再叠加OpenMP线程会引发CPU资源争抢。可以设置环境变量限制OpenMP线程数export OMP_NUM_THREADS1这样每个进程只占一个CPU核避免超线程调度带来的性能下降。如果你跑的是单进程大任务可以适当调高OpenMP线程数尝试让性能更优。6.3 磁盘与内存习惯PyRosetta在运行过程中会写一些临时文件和日志尤其是在大规模并行任务里输出文件会快速增长。建议定期清理。还有一个容易被忽略的点PyRosetta的Python对象占用的内存在调用pyrosetta.init()后会初始化一些全局资源脚本退出时释放。如果你在一个长循环里反复创建Pose对象及时释放引用、不要随手保存所有中间结果到列表里否则内存会迅速上涨。写长脚本时多用函数封装让局部变量及时弹出作用域。最后再分享一个小技巧安装配置都稳定下来之后我习惯在项目入口文件顶部写一个统一初始化函数import pyrosetta def init_pyrosetta(extra_options): pyrosetta.init(-mute all extra_options)这样后续所有脚本都调用这个入口不用每次敲-mute all也方便在需要调试时追加额外参数。如果你需要在多台机器间迁移环境最好把conda env export environment.yml留一份换机器时直接重建省得重新踩一遍版本坑。PyRosetta的安装其实不难只是坑比较集中把环境、license、版本这三件事理顺后面用起来就顺手多了。本文还有配套的精品资源点击获取