Python 3.13降级到3.11：一次d2l库安装的踩坑与解决全记录

一、问题背景

最近我在跟随bibi博主 李沐学习深度学习时，遇到了一个典型但又令人头疼的问题：在Python 3.13.13环境下安装d2l库时，反复出现各种版本兼容性错误，最终不得不将Python版本从3.13降级到3.11才解决问题。整个过程耗时约3小时，现将踩坑经历和解决方案整理成文，希望帮助遇到同样问题的读者少走弯路。

二、踩坑全记录

坑位1：pkgutil.ImpImporter错误——Python 3.13与旧版库的ABI不兼容

错误现象：

bashAttributeError: module 'pkgutil' has no attribute 'ImpImporter'. Did you mean: 'zipimporter'?

原因分析： Python 3.10开始逐步废弃pkgutil.ImpImporter，到Python 3.12正式移除了这个属性。然而，许多旧版本的库（特别是setuptools中的pkg_resources模块）仍然引用了这个已删除的属性。当pip尝试从源码编译这些库时，就会触发致命错误。

关键报错堆栈显示：

File "/tmp/pip-build-env-*/overlay/lib/python3.13/site-packages/pkg_resources/__init__.py", line 2172
register_finder(pkgutil.ImpImporter, find_on_path)

这意味着构建环境中的setuptools版本过旧，无法在Python 3.13上正常工作。

坑位2：numpy 1.23.5编译失败——源码构建死循环

错误现象：

bashGetting requirements to build wheel ... error
error: subprocess-exited-with-error

原因分析： 即使我已经安装了numpy 2.2.5（该版本本身支持Python 3.13），但在安装d2l时，pip的依赖解析器拉取了numpy 1.23.5的源码包（.tar.gz）尝试本地编译。由于这个旧版numpy的构建脚本调用了已损坏的pkg_resources，导致编译彻底失败。

这里的关键教训是：pip依赖解析器有时不会考虑已安装的包，而是根据依赖树重新拉取特定版本。

坑位3：setuptools版本冲突——环环相扣的依赖链

错误现象：

bashERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
torch 2.12.1 requires setuptools<82, but you have setuptools 82.0.1 which is incompatible.

原因分析： PyTorch 2.12.1要求setuptools<82，而我的环境中默认安装了setuptools 82.0.1。即使我执行了降级命令pip install 'setuptools<82' -U，由于pip缓存机制和环境路径问题，降级并未真正生效。

坑位4：尝试修复反而加剧问题——治标不治本的代价

在遇到上述错误后，我尝试了以下修复方式：

1. 升级pip、setuptools和wheel：部分缓解了问题，但d2l的依赖链中仍有旧版库。
2. 手动修改pkg_resources文件：将pkgutil.ImpImporter替换为zipimport.zipimporter，但这种方法治标不治本，无法从根本上解决ABI不兼容问题。
3. 强制使用预编译wheel：pip install --only-binary=:all:，但Python 3.13+Linux平台下，许多旧版库根本没有预编译wheel，这个方案在关键环节失效。

三、最终解决方案：降级Python到3.11

为什么降级是最稳妥的方案？

正如d2l官方讨论区指出的：遇到d2l这类明确报错的库时，核心矛盾是它们的预编译wheel依赖旧版CPython ABI，而Python 3.12+的PyModuleDef_Init和类型系统变更已破坏兼容性。

虚拟环境（venv）可以隔离包依赖，但无法绕过ABI不匹配这个二进制层面的硬性限制

。唯一的可靠方案是创建一个Python 3.11的独立环境。

降级操作步骤（Linux系统，以Ubuntu为例）

1. 安装pyenv（Python版本管理器）

bash# 安装依赖
sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev

# 安装pyenv
curl https://pyenv.run | bash

2. 配置环境变量

bashecho 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

3. 安装Python 3.11并设为默认

bashpyenv install 3.11.9
pyenv global 3.11.9
python --version  # 应输出 Python 3.11.9

4. 在新环境下安装d2l

bashpip install --upgrade pip setuptools wheel
pip install numpy==1.24.3  # 兼容d2l的旧版numpy
pip install d2l

安装成功后，所有错误完全消失，d2l库正常工作。

四、经验总结与避坑指南

核心教训

1. Python版本选择很重要：对于深度学习和科学计算项目，建议优先选择稳定版的前一个次版本（如3.11），而不是最新版（3.13）。最新版往往需要时间让生态圈适配。
2. 不要盲目追求最新Python版本：d2l官方推荐Python 3.10~3.11，这不是没有道理的。在生产环境和学习项目中，稳定性优先于新特性。
3. 版本管理工具是必需品：推荐使用pyenv（Linux/macOS）或conda来管理多个Python版本，可以随时切换，避免手动卸载带来的残留问题。
4. pip的依赖解析器有局限：pip在解析复杂依赖时，有时会选择旧版本或忽略已安装的包，导致意外的版本冲突。建议使用pip check定期检查依赖一致性。

避坑清单

表格

五、结语

这次踩坑经历让我深刻认识到：在Python生态中，版本兼容性是一门需要认真对待的学问。对于不同的项目需求，选择正确的Python版本和工具链，可以节省数小时甚至数天的调试时间。

如果你也遇到了类似的问题，我的建议是：果断降级到Python 3.11，使用pyenv或conda管理版本，这是最省时省力的方案。不要试图在所有旧瓶装新酒的道路上死磕——有时候，退一步海阔天空。