1. 为什么非要自己编译 PyMOL开源版到底香在哪在结构生物学、药物设计或者分子模拟这个圈子里PyMOL 基本是人手一个的分子可视化工具。网上能搜到一大堆编译、安装教程但是大部分都是讲 conda 直接装预编译包或者下载教育版图形界面安装包真正涉及到从源码自己编译的教程要么年份太久要么用的是已经被官方弃用的老流程。这篇文章把我的实际操作过程、踩过的坑、排查思路完整整理出来希望能帮你少走弯路。需要先说清楚一件事这里说的“开源版 PyMOL”指的就是 GitHub 上 Schrodinger 公司维护的 pymol-open-source 仓库它基于经典 PyMOL 内核以开放源码的形式发布。它和官方教育版、商业版的差别主要体现在少了一些授权闭源的插件和部分功能封装但核心的分子渲染、结构比对、表面计算、PDB 文件处理、密度图可视化这些功能都是完整的。换句话说把它编译出来日常做科研、做教程、跑自动化脚本完全够用。如果你还在纠结“我直接下载一个编译好的二进制包不就行了”那我先讲讲自编译到底香在哪可以跟上游代码保持同步拿到最新版本的特性和 bug 修复可以自己控制 Python 版本、Qt 版本避免预编译包和老系统环境冲突可以自定义安装路径不污染系统环境适合服务器上没有 sudo 权限的场景可以打开调试符号、启用内部 profiling方便研究源码甚至二次开发很多功能插件比如实验室内部脚本、自动化分析管线对源码结构有依赖编译版更容易扩展。当然编译也确实绕不过一些系统依赖、CMake 配置、Qt 构建这类问题。这篇文章的主体就是围绕这些展开。1.1 开源版与预编译版、教育版的关键差异这里有个特别容易踩迷糊的点PyMOL 社区里经常出现“开源版”和“教育版”的说法但它们不是同一个东西。先看开源版。官方的开源仓库地址是https://github.com/schrodinger/pymol-open-source采用兼容开源许可证目前是 PyMOL 的开放式许可证本质上属于 BSD 风格。源码包里有setup.py、CMakeLists.txt、layer0到layer3的 C/C 核心代码还有modules里的大量 Python 逻辑。只要你的环境满足依赖就可以自行编译。再来看教育版和商业版。这两个版本由 Schrodinger 以二进制安装包的形式分发界面更友好带有一些面向教学的整合功能但源码不开放也无法通过 pip 或者源码方式安装。很多新手在网上搜到“PyMOL 安装”往往会下载到教育版.dmg或者.exe。那没问题但我这篇文章针对的是源码编译强调的是开源仓库自己的构建体系。1.2 编译任务拆解你真正要面对的三个环节我第一次编译 PyMOL 时最大的错觉是“只要跑 make 就结束了”。后来才理解PyMOL 的构建链路远不止一次编译它其实分成三个环节C/C 核心层编译这一层负责分子渲染、几何计算、OpenGL 调用、表面生成这些性能敏感的部分编译单元多对编译器和 C 标准库版本敏感Python 绑定层生成PyMOL 的 Python APIpymol模块通过 SWIG 或者 C 扩展模块暴露给解释器所以你要保证 Python 开发头文件、Python 解释器版本和编译出的动态库严格一致Qt/GUI 前端装配开源版默认的图形界面基于 PyQt启动pymol时会在 Python 环境下加载pymol包再由 PyQt 驱动主窗口。如果 PyQt 版本、QScintilla 组件、OpenGL 驱动不健全程序能 import 成功但一打开窗口就崩溃或者闪退。把这几个层次分开理解之后再去排查编译错误就不会一头雾水了。很多报错看起来是在/bin/sh或者 cmake 阶段蹦出来的根子却是其中一个环节没有满足前置条件。1.3 我建议的编译路线图结合我的使用经验如果你不是非要深入 C 二次开发最简单的路线是先安装基础编译工具和 Python 开发头文件再安装 Qt5、PyQt5、QScintilla 相关依赖接着克隆源码用 CMake 做预编译配置然后执行编译和安装最后在命令行验证pymol能否启动、能否加载 PDB、能否画密度图density map。接下来的内容会按这个路线逐步展开。这样编排也有一个好处每一步出现问题时你都知道该去检查哪一层不会因为一个 Qt 报错就把整个源码重下载一遍。2. 编译前的环境准备依赖装不对后面全是坑这一章节极其重要。我见过太多案例明明命令一行不差最后卡在 OpenGL 或者 Python.h 找不到上根本原因就是依赖没有按版本要求对齐。不要小看这一步PyMOL 的 CMake 过程会同时探测图形、文本、XML、Python、Qt 五类开发库任何一项缺失都会导致整个配置失败。2.1 核心依赖到底有哪些先列一个宏观清单再讲每个依赖的作用。以下这些是编译开源版 PyMOL 时的常见依赖项编译工具链gcc、g、make构建系统cmake某些老版本还用到 autotools但不推荐版本控制git用来拉取源码和切换分支Python 与开发包python3、python3-devOpenGL 相关libgl1-mesa-dev、libglew-dev、freeglut3-dev图像与文本libpng-dev、libfreetype-devXML 解析libxml2-devQt 与 GUI 绑定qtbase5-dev、pyqt5-dev、qscintilla2-qt5-dev其中最容易漏掉的是libglew-dev和freeglut3-dev。PyMOL 的渲染循环用到 OpenGL而 GLEW 负责在运行时动态加载 OpenGL 扩展指针如果只装了 Mesa 的基础库CMake 可能会通过但编译或者运行时会出现 GL 函数找不到的情况。qscintilla2-qt5-dev也容易漏。PyMOL 内嵌的“命令输入栏”就是底部那个可以输入fetch 1abc、rotate命令的白框在源码构建中会用到 QScintilla 这个基于 Qt 的代码编辑器控件。没有它编译时不一定立刻报错因为很多发行版会以可选组件的形式处理但如果脚本里用了相关模块运行阶段就会出问题。2.2 我在 Ubuntu / Debian 系的做法以 Ubuntu 22.04 LTS 为例这一步基本是sudo apt update sudo apt install -y build-essential git cmake python3 python3-dev \ libgl1-mesa-dev libglew-dev freeglut3-dev \ libpng-dev libfreetype6-dev libxml2-dev \ qtbase5-dev pyqt5-dev qscintilla2-qt5-dev装完之后建议立刻检查 Python 版本因为后续编译时PYTHON_EXECUTABLE要和系统 python 对齐python3 --version which python3如果系统里有多个 Python比如用 pyenv 或 conda 管理一定要确保接下来使用的 cmake 命令里的PYTHON_EXECUTABLE指向同一个解释器否则编译出的_pymol扩展模块会被 Python 解释器拒绝加载报错类似undefined symbol: _Py_NoneStruct。这个话题我会在第 4.3 节详细展开。2.3 macOS 和其他平台的小补充macOS 上我通常用 Homebrew 先装python3.11、qt5、glew、glu、freeglut、libxml2。在 Apple Silicon 上需要注意OpenGL 框架虽然系统自带但 CMake 找的路径和 x86_64 时代略有不同。建议在 CMake 阶段显式指定cmake .. -DOPENGL_INCLUDE_DIR$(brew --prefix)/includeWindows 上的情况更复杂。开源版的官方构建流程主要以 Linux 和 macOS 为主Windows 上要么用 WSL要么用 MSYS2。我个人在 Windows 上的经验是直接用 WSL2 装 Ubuntu 镜像再在 WSL 里按 Linux 流程编译比在原生 Windows 上折腾 Qt 工具链顺利得多。如果你非要在原生 Windows 编译MSYS2 的环境里需要额外安装 mingw-w64 系列的 Qt、Python、GLEW 包路径和库名都不一样建议新手不要轻易尝试。另外如果你是要在自己的笔记本电脑上跑结构生物学课程作业或者做毕业设计WSL2 里编译已经完全够用没必要为难自己。2.4 依赖版本不匹配带来的连锁反应这里分享一个真实案例。有一次我在 CentOS 7 上编译系统自带 Python 2.7而 PyMOL 源码较新版本已经要求 Python 3.6。我图省事装了 python38但没有把python3-config路径和 CMake 的PYTHON_EXECUTABLE对齐结果编译出的模块一import pymol就段错误排查了很久才发现是 Python ABI 不一致。所以我的建议很明确编译之前先确定 Python 版本并且让 CMake、python3-dev、python3三者保持一致最好全部来自同一个发行版仓库避免混用源码编译的 Python 和系统自带 Python。这个原则不仅适用于 PyMOL编译其他带 Python 绑定的 C 项目比如 OpenCV、VTK、一些深度学习工具时同样适用。3. CMake 配置与源码编译全流程依赖准备好之后接下来进入正式流程。整个环节最核心的是 CMake 预编译配置很多人一听到“cmake”就头大其实只要理解了它的逻辑它就是一台“生成 Makefile 的自动化翻译机”。你告诉它“我要装到哪个目录、用哪个 Python、有哪些依赖”它根据这些信息生成对应的构建脚本仅此而已。3.1 获取源码git clone 与分支选择首先把源码拉到本地git clone https://github.com/schrodinger/pymol-open-source.git cd pymol-open-source如果你对稳定发布更敏感可以查看当前 taggit tag git checkout v2.5.0 # 或者你需要的版本这里有两个细节值得注意。第一不要直接克隆后切到 master 分支就跑生产环境的项目master 是滚动开发分支虽然也能编译但接口和构建参数可能在变第二如果你后续要运行很多依赖于pymolPython API 的脚本最好记录一下你的源码 commit 号方便之后复现。比如我习惯把 commit 号写进实验记录的备注里git log -1 --format%H这样半年后回去重新跑分析时还能知道你当时用的是哪一版 PyMOL。这在科研项目的可复现性上价值巨大。3.2 CMake 预编译配置写法官方推荐的现代构建方式是通过 CMake 生成构建文件然后make。以源码根目录为基准mkdir build cd build cmake .. \ -DCMAKE_INSTALL_PREFIX$HOME/software/pymol \ -DPYTHON_EXECUTABLE$(which python3) \ -DPYTHON_INCLUDE_DIR$(python3 -c import sysconfig; print(sysconfig.get_paths()[include])) \ -DPYTHON_LIBRARY$(python3 -c import sysconfig; print(sysconfig.get_config_var(LIBDIR)))每个-D参数的意思我拆开讲CMAKE_INSTALL_PREFIX最终安装路径我习惯装在用户目录下不污染系统PYTHON_EXECUTABLE告诉 CMake 用哪个 Python 解释器来做绑定层和脚本处理PYTHON_INCLUDE_DIRPython.h 头文件的位置如果系统里 python3-dev 装好了一般可以通过 sysconfig 获取PYTHON_LIBRARYPython 动态库所在目录某些环境需要再精确到libpython3.x.so的文件路径。如果你不想在命令行里手动算这些路径可以写一个简单的配置文件丢给 CMake。比如创建一个my_options.cmake里面放set(CMAKE_INSTALL_PREFIX $ENV{HOME}/software/pymol) set(PYTHON_EXECUTABLE $ENV{HOME}/miniconda3/bin/python) set(PYTHON_INCLUDE_DIR $ENV{HOME}/miniconda3/include/python3.11) set(PYTHON_LIBRARY $ENV{HOME}/miniconda3/lib/libpython3.11.so)然后在 build 目录里执行cmake .. -C my_options.cmake-C的写法在社区讨论里经常被称为“cmake 预编译的写法”本质就是在生成 Makefile 之前预先注入 CMake 缓存变量。这样做的好处是多人协作时环境相关的配置可以统一管理避免每次都在命令行拼一长串参数。我自己的习惯是每台机器上都保留一个pymol_build_options.cmake文件换机器后直接复用省掉一大半排查时间。CMake 配置成功后终端会显示构建系统的配置摘要。如果你看到Build files have been written说明这一步顺利通过。如果报错提示找不到 Qt、Python、OpenGL优先回到第 2 章检查依赖。3.3 编译、安装与验证接下来是编译本身make -j$(nproc)-j参数表示并行编译的线程数nproc会返回当前 CPU 核数。第一次编译可能会比较久尤其在你的 CPU 核数多的情况下并行编译能明显缩短时间但如果你内存较小建议控制并行数比如make -j4。这个建议不是空话PyMOL 里某些 C 编译单元展开后极其吃内存并行度开高了轻则变慢重则被系统 OOM Killer 直接杀掉。编译完成后安装make install安装结束后把bin目录加入PATH同时确认 Python 模块可以被导入export PATH$HOME/software/pymol/bin:$PATH python3 -c import pymol; print(pymol.cmd.get_version())如果能够输出版本号说明 C 内核、Python 绑定和 PyQt 前端三部分全部装配完成。为了以后每次打开终端都能直接使用pymol可以把export PATH...这行写进~/.bashrc或者~/.zshrc。3.4 快速启动图形界面和命令行模式图形界面模式直接运行pymol如果服务器没有显示器或者你只需要用 Python API 做批量处理可以进入“无头模式”headless modepymol -cq-c表示命令行模式-q表示减少启动日志。在这种模式下你可以执行fetch 1cbs、load xxx.pdb、show surface这类命令其中fetch依赖网络从 PDB 数据库拉取结构文件。无头模式是我在日常批量渲染中最常用的方式后面第 5 章我会给出一套可直接用的示例命令。4. 高频编译错误与排查实录这一章是整篇文章里我最想写的部分。编译 PyMOL 很少有一遍过的下面这些报错我全部在实际环境里遇到过每个都对应一个真实场景。我尽量还原当时的报错现场和排查顺序这样你遇到类似问题时可以按图索骥。4.1 QScintilla 相关的错误QScintilla 在 PyMOL 里负责命令行输入控件它在编译阶段经常以“找不到头文件”或者“Python 绑定不全”的形式出现。典型报错之一fatal error: Qsci/qsciglobal.h: No such file or directory排查思路先确认 qscintilla 开发包是否已经安装。在 Ubuntu 上dpkg -l | grep qscintilla如果没有安装sudo apt install libqscintilla2-qt5-dev还有一类情况是 PyQt 的 QScintilla Python 包缺失。当你编译完 PyMOL启动后输入框区域不显示或者程序报ModuleNotFoundError: No module named PyQt5.Qsci这是因为 PyQt5 的部分组件是通过单独包分发的。Ubuntu 上需要sudo apt install python3-pyqt5.qsci如果你是在 conda 环境里编译可以用conda install -c conda-forge pyqt qscintilla2这里有一个容易引发连锁反应的细节如果你手动下载 QScintilla 源码并编译安装一定要保证它和 PyQt5 用的是同一个 Qt 版本而且 Python 绑定所依赖的 SIP 版本也必须匹配。否则会出现“QScintilla 装上了但 PyQt5 里 import 不到”的诡异情况。4.2 OpenGL / GLU 头文件缺失PyMOL 的核心渲染层调用 OpenGL 和 GLU如果系统缺少开发头文件编译时会出现类似fatal error: GL/glu.h: No such file or directory或者 CMake 阶段直接找不到 OpenGLCould NOT find OpenGL (missing: OPENGL_glu_LIBRARY)解决办法非常简单但有些人会卡很久sudo apt install libglu1-mesa-dev freeglut3-devlibglu1-mesa-dev提供 GLU 库freeglut3-dev提供更多窗口工具函数。PyMOL 编译时并不是一定需要完整的 Qt 窗口才需要 OpenGL它连离屏渲染例如把分子渲染成图片而不弹窗也需要 GL 环境。我记得在某个裸机服务器上第一次跑ray命令时界面没弹出来但任务管理器里能看到 CPU 在疯狂计算最终 PNG 文件正常生成靠的就是这套离屏 GL 链路。4.3 Python 版本与开发头文件不一致这个报错往往不是最直观的它可能出现在编译中途也可能出现在安装后启动瞬间。编译时报错Python.h: No such file or directory说明缺少python3-dev安装后重试即可。但还有一种更有迷惑性的场景编译完全通过import pymol却报ImportError: /usr/local/lib/python3.10/dist-packages/pymol/_pymol.cpython-310-x86_64-linux-gnu.so: undefined symbol: _Py_NoneStruct这个_Py_NoneStruct符号在不同 Python 版本中是不同的尤其是 Python 3.10 之后改动频繁。遇到这种问题先确认编译时的PYTHON_EXECUTABLE和运行时 import 用的 Python 是不是同一个解释器。如果服务器上有 conda 和系统 Python 并存极容易出现“CMake 用的系统 Python运行时用了 conda Python”的情况。我的排查命令组合which python3 python3 -c import sys; print(sys.executable)再对比 CMake 缓存里的PYTHON_EXECUTABLEgrep PYTHON_EXECUTABLE build/CMakeCache.txt两者必须一致。这个检查也适用于其他 C 扩展模块的编译问题算是排查这类问题的一个通用套路。4.4 Qt / QML 编译错误有些较新版本的 PyMOL GUI 依赖 Qt Quick / QML 组件编译时可能遇到Could not find a package configuration file provided by Qt5Qml或者运行时报module QtQuick is not installed这种情况下除了qtbase5-dev还要安装额外的 Qt 模块sudo apt install qtdeclarative5-dev qml-module-qtquick2在更新版本或者使用 Qt6 时还要注意 PyMOL 源码的 CMake 默认找的是什么版本。如果你系统里同时装了 Qt5 和 Qt6CMake 可能优先找到 Qt6但 PyMOL 的某个依赖组件还没适配 Qt6就会出现“QML 编译错误”。这时可以在 CMake 阶段显式指定cmake .. -DQT_DIR/usr/lib/x86_64-linux-gnu/cmake/Qt5QML 报错还有一个隐蔽来源某些经过精简的 Docker 镜像或者轻量系统根本没有安装 Qt Quick 模块你只装了qtbase5-dev觉得“Qt 应该全了”但实际libqt5qml5、libqt5quick5都没有。所以出现问题后先别急着改源码直接检查这几个包是否存在会更高效。4.5 其他零散报错与排查速查表除了上面四个大项我还整理过一个速查表很多问题都能对号入座报错内容原因处理方式No rule to make target ...make 目录不对或 CMake 缓存脏删掉 build 目录重新 cmakelibGL.so not found显卡驱动的 32/64 位库不匹配安装libgl1-mesa-glx必要时检查 LD_LIBRARY_PATHcannot find -lpython3.11Python 动态库未安装或路径未指定安装libpython3.11-dev并在 CMake 中指定PYTHON_LIBRARYgcc: fatal error: Killed signal terminated program cc1plus内存不足并行编译导致 OOM降低make -j并行度或临时创建 swapImportError: libqxcb.so: cannot open shared object file图形界面依赖的 Qt 平台插件缺失安装libqt5gui5或者检查QT_QPA_PLATFORM变量这里我特别想提醒一个容易忽略的点如果你是在 Docker 容器或者轻量虚拟机上编译内存轻易不要少于 2 GB。PyMOL 的 C 编译单元里很多模板展开非常吃内存我遇到过 1 GB 内存的容器编译到一半直接被 OOM Killer 干掉的情况。业界有一个快速缓解办法先关闭图形界面跑make -j2同时给系统加上 swap 空间能避免大部分 OOM。4.6 为什么有些人用一键安装脚本也能成功最近“鱼香ROS一键安装”这类脚本在机器人社区很火有人问能不能用类似思路装 PyMOL。事实上PyMOL 也有社区维护的一键安装方案比如 Ubuntu 上直接sudo apt install pymol或者 conda 上conda install -c conda-forge pymol-open-source。这些方案之所以省事本质上是把第 2 章的依赖和第 3 章的编译步骤全部封装好了。但如果你自己做科研项目我仍然建议至少手动走一遍编译流程。原因很简单你要用的插件、脚本、自动化管线很可能直接调用pymol模块的内部接口只有理解了模块安装到了哪里、Python 路径是什么、Qt 版本是什么才能定位那些“源代码没错却跑不起来”的诡异问题。另外一键安装通常会把 PyMOL 放到系统全局路径在集群环境里可能导致多个用户互相干扰自编译到用户目录就没有这个烦恼。5. 装好之后别急着关终端功能验证与日常使用要点编译安装成功的成就感确实很大但我建议先别急着打开一个炫酷的分子就开始旋转先花几分钟做几项基础验证确保渲染、Python API、密度图处理这些核心功能都正常。这一章主要解决“装好了怎么确认没问题”以及“怎么在日常工作中用好它”这两件事。5.1 快速功能自检最简单的自检命令pymol -cq -d fetch 1cbs; hide everything; show cartoon; raytrace 320,240这条命令的含义是启动 PyMOL 命令行模式从 PDB 数据库拉取 1cbs 结构隐藏所有默认显示只显示卡通模型再以 320x240 的分辨率做一次光线追踪渲染。如果没有报错且目录下生成了 PNG 图片说明底层 OpenGL 调用、PDB 网络下载、渲染管线都是正常的。如果你想导出高质量图片可以用png命令比如pymol -cq -d fetch 1cbs; hide everything; show cartoon; ray 1280,960; png my_render.png实测下来ray之后直接png能保证输出的是光线追踪渲染结果而不是屏幕截图的低清版本。如果你不调用raypng默认保存的是当前 GL 窗口的离屏渲染画质取决于屏幕分辨率这对于论文配图来说往往不够。5.2 PDB 文件与密度图处理的常用实操编译版和预编译版在 PDB 处理上没有任何区别但你既然亲手编译了自己的一份 PyMOL理解这些底层逻辑会更有意义。加载本地 PDB 文件load example.pdbPyMOL 会自动解析原子坐标、氨基酸序列、B-factor 等信息从 PDB 数据库在线拉取fetch 1cbs依赖网络适合快速获取标准化结构查看晶体学信息和密度图如果 PDB 文件包含CRYST1记录PyMOL 会自动建立晶胞参数用symmetry命令可以显示/隐藏对称分子加载密度图常见的密度图格式包括 .ccp4 / .mrc / .map。命令是load density.ccp4, mymap isomesh mesh1, mymap, 1.0这里的isomesh是等值面网格命令第三个参数是等值面水平sigma 倍数。密度图在结构解析和模型修建中非常常用尤其是你处理冷冻电镜数据或者晶体衍射数据时。如果你是第一次用建议先从fetch 2MCP这种带实验数据的结构开始边看密度图边调整等值面水平体会一下不同 sigma 阈值下网格的显示差异。查看和操作表面show surface会生成分子表面表面计算比较耗费 CPU如果以后需要批量跑表面建议用脚本而不是手动一个一个点。例如fetch 1cbs hide everything show surface set surface_color, lightblue ray 800, 600 png surface.png5.3 后续扩展与维护建议编译版 PyMOL 的优势之一是可以自行扩展 Python API。你可以在~/.pymolrc文件里写入自定义启动逻辑比如设置默认背景色、加载自定义插件路径、预定义常用命令别名。一个简单的示例from pymol import cmd cmd.set(ray_opaque_background, 0) cmd.set(cartoon_transparency, 0.2)另外建议设置环境变量PYMOL_SCRIPTS和PYMOL_DATAexport PYMOL_SCRIPTS$HOME/pymol-scripts export PYMOL_DATA$HOME/software/pymol/data这样自定义脚本和数据文件都有统一位置后续写自动化分析流程时不会乱。如果你的工作流里经常要处理批量结构文件可以自己写一个 Python 脚本循环加载目录下的所有 PDB统一输出 PNGimport glob import pymol from pymol import cmd pymol.finish_launching([pymol, -cq]) for pdb in glob.glob(*.pdb): cmd.load(pdb) cmd.hide(everything) cmd.show(cartoon) cmd.png(pdb.replace(.pdb, .png), width800, height600, dpi150, ray1) cmd.delete(all)这类脚本在生产环境里非常实用比手动一个个打开 PyMOL 再截图高效得多。5.4 升级源码版本时怎么做如果你希望跟上新版本升级也是一门学问。我的做法是cd pymol-open-source git pull rm -rf build mkdir build cd build cmake .. make -j$(nproc) make install这里重申一句升级前最好备份~/.pymolrc和你的插件目录否则新的安装包可能会覆盖部分默认配置。虽然概率不高但我在 PyMOL 升级时遇到过自定义插件路径被重置的情况备份一下总没坏处。如果你在用某个内部脚本且升级后发现 API 行为变化可以通过git diff查看上游改动定向适配而不是把整个环境推倒重来。关于 PyMOL 的编译安装我能分享的核心经验就这些。实际编译过程中每个人遇到的报错可能都不一样但只要把握住“C 核心层、Python 绑定层、Qt/GUI 前端”这三条线索把依赖和版本对齐绝大多数问题都能迎刃而解。我个人在实际操作中的体会是不要怕编译报错每一个报错都在告诉你环境里缺了哪一块“拼图”把它补上整个构建链条就通了。最后再分享一个小技巧——把 CMake 的配置参数写成一个文件保存起来下次重装或者换机器时你会感谢自己当初多做了这一步。