📚 课程目录第3章 Python环境配置报错

好的，这是为您生成的《AutoDock报错故障排除实战教程》第三章正文内容片段（HTML格式），聚焦Python环境配置导致ADT GUI无法启动的故障排除。

Python环境配置报错：ADT GUI无法启动

这个报错，我敢说十个用ADT的人里，至少七八个都撞上过。你装好了MGLTools，双击桌面图标，结果啥反应没有。或者终端里敲了adt，啪地弹出一段红色ImportError，然后闪退。别急，这大概率不是软件坏了，而是你的Python环境在"闹脾气"。这章咱们就专门治这个病。

3.1 先搞清楚：ADT到底想要什么样的Python环境

很多人上来就瞎试，装完PyQt装NumPy，折腾半天还是不行。你想想看，ADT本身是MGLTools的一部分，它启动时要用到自己捆绑的Python解释器和一套特定的库。不是你系统里的Python 3.10就一定能用。

我个人的习惯是，第一步先看MGLTools的版本号。不同版本对Python和Qt的依赖完全不同，搞错了就是浪费一上午。

MGLTools版本	Python版本	GUI工具包	关键依赖
1.5.6 / 1.5.7 （经典版）	Python 2.7 （必须）	PyQt4 或 PySide	NumPy, PIL
1.6.0 及以上	Python 3.6 ~ 3.8	PyQt5 或 PySide2	NumPy, Pillow

嗯，这里要特别注意：ADT 1.5.x系列的启动脚本会强制调用Python 2.7。如果你系统默认的python指向Python 3，那就会直接报版本错误。我记得有个项目里，师弟就是没注意这个，卡了整整两天。

3.2 最常见的五个坑，你踩过几个？

下面这五个问题，几乎覆盖了90%的ADT GUI启动失败案例。我按出现频率排了个序：

Python版本冲突 —— 系统默认Python不是ADT要的那个版本。
PyQt缺失或版本不对 —— ADT界面全靠它渲染，没有PyQt，GUI根本起不来。
NumPy / PIL未安装 —— 启动时导入失败，直接崩溃。
PYTHONPATH环境变量没设对 —— ADT找不到自己的库包（MGLToolsPckgs）。
Qt平台插件问题 —— Linux上最常见，"Could not load the Qt platform plugin 'xcb'"。

你看，这五个问题里，除了第5个跟系统库有关，前面四个全是Python环境的事。所以把Python环境理顺了，ADT基本就能跑起来。

3.3 诊断三步走，别跳步

碰到ADT打不开，别慌。我一般按下面三步走，基本十分钟内能定位问题。

第一步：看报错信息

在终端里启动ADT，不要双击图标。这样你能看到完整的报错回溯：

# Linux / macOS
adt

# 或者用你的安装路径
/path/to/mgltools/bin/adt

如果是Windows，在cmd里运行：

"C:\Program Files\MGLTools\bin\adt.bat"

把终端里红字的部分复制下来。我跟你讲，90%的问题看报错的第一行就能知道方向。

第二步：查Python版本

确认ADT启动脚本实际调用了哪个Python：

# 看看adt脚本里写的python解释器路径
head -1 /path/to/mgltools/bin/adt

# 或者直接检查当前系统默认Python
python --version
python -c "import sys; print(sys.executable)"

第三步：检查关键库能否导入

用ADT实际使用的那个Python解释器来测试：

# 假设ADT用的是 /usr/bin/python2.7
/usr/bin/python2.7 -c "import PyQt4; print('PyQt4 OK')"
/usr/bin/python2.7 -c "import numpy; print(numpy.__version__)"
/usr/bin/python2.7 -c "import PIL; print('PIL OK')"

这一步哪个报错，就是哪个缺失。非常直接。

3.4 对症下药，手把手修

诊断出来具体问题后，下面是针对性的解决方案。

情况A：Python版本不对

如果你发现ADT需要Python 2.7但系统默认是Python 3，别去改系统默认，那会搞崩其他程序。正确的做法是：

# 安装Python 2.7（如果还没装）
# Ubuntu/Debian
sudo apt-get install python2.7

# 修改ADT启动脚本，让它显式调用python2.7
# 编辑 /path/to/mgltools/bin/adt
# 找到类似这行：
# exec python ...
# 改成：
exec python2.7 ...

千万不要直接改系统里 /usr/bin/python 的软链接指向。我曾经见过有人把系统Python 3的软链接改成Python 2.7，结果桌面环境崩了，连终端都打不开。ADT的事就在ADT内部解决。

情况B：PyQt缺失

ADT 1.5.x系列需要PyQt4，安装方式：

# Ubuntu / Debian
sudo apt-get install python-qt4

# CentOS / RHEL
sudo yum install PyQt4

# macOS (用Homebrew)
brew install pyqt@4

# 如果你是用pip安装的MGLTools环境
pip install PyQt4  # 注意：PyQt4已停止维护，建议用系统包管理器

如果是ADT 1.6.x及以上，安装PyQt5：

pip install PyQt5

情况C：NumPy / PIL缺失

这个最简单，直接用pip装：

# 使用ADT对应的Python解释器来装
/usr/bin/python2.7 -m pip install numpy
/usr/bin/python2.7 -m pip install Pillow

一个小技巧：装完依赖后，不需要重启电脑，重新开一个终端再启动ADT就行。我遇到过有人装完NumPy后重启了三次电脑，其实完全没必要。

情况D：PYTHONPATH变量没设对

ADT启动时需要找到MGLToolsPckgs这个包目录。检查一下：

# 查看当前PYTHONPATH
echo $PYTHONPATH

# 应该包含MGLToolsPckgs的路径，类似：
# /opt/mgltools/MGLToolsPckgs

# 如果没有，手动设置（临时生效）
export PYTHONPATH=/opt/mgltools/MGLToolsPckgs:$PYTHONPATH

# 然后试着启动ADT
adt

如果确认是PYTHONPATH的问题，建议永久写到配置里：

# 编辑 ~/.bashrc （Linux）或 ~/.bash_profile （macOS）
echo 'export PYTHONPATH=/opt/mgltools/MGLToolsPckgs:$PYTHONPATH' >> ~/.bashrc
source ~/.bashrc

3.5 验证：真修好了吗？

修完之后，别急着欢呼。做两件事验证一下：

验证1：命令行测试

用ADT的Python解释器执行一个完整的导入测试：

# 一次性测试所有关键组件
/usr/bin/python2.7 -c "
import sys
print('Python:', sys.version)
import PyQt4
print('PyQt4 OK')
import numpy
print('NumPy:', numpy.__version__)
import PIL
print('PIL OK')
print('All dependencies satisfied!')
"

验证2：启动ADT GUI

直接启动ADT，看是否能正常弹出图形界面：

adt &

如果界面正常弹出，工具栏、菜单栏都显示完整，没有报错窗口，那恭喜你，问题解决了。

如果还是起不来，别灰心。回到3.3节重新走一遍诊断流程，大概率是有某个细节漏掉了。我遇到过最离谱的一次，是用户装了两个版本的MGLTools，PATH环境变量指向了旧版本的启动脚本，修了三次才发现。所以，仔细看报错信息里的路径，它不会骗你。