我不止一次看到有人卡在《动手学深度学习》d2l-zh的环境配置阶段运行pip install d2l等半天然后看着满屏红色报错发懵或者好不容易装上一import d2l又提示模块不存在。作为从MXNet时代一路用到PyTorch版的读者我可以负责任地说这些报错大多数不是操作失误而是没理解d2l-zh这套环境的安装逻辑和版本匹配关系。这篇博文就围绕如何用Anaconda正确安装d2l-zh包来展开把完整安装链路和典型报错的排查思路讲透适合刚上手深度学习、准备跟着李沐老师的书跑代码的初学者参考。1. 为什么d2l-zh安装总翻车先搞懂它到底是什么1.1 d2l-zh不是一个软件而是一套带配方的代码库很多新手把d2l-zh当成普通的pip包来理解这是安装翻车的根源。d2l-zh本质上是《动手学深度学习》的配套代码仓库里面包含每章对应的Jupyter notebook文件而d2l这个Python包是仓库作者封装的一套辅助工具库帮你省去重复编写数据加载、训练循环、绘图函数的功夫。安装d2l-zh的完整链路其实是这样的安装Anaconda提供Python解释器和包管理工具conda创建独立虚拟环境隔离项目的Python版本和依赖在虚拟环境里安装深度学习框架PyTorch / TensorFlow / MXNet三选一安装d2l工具包安装并运行Jupyter Notebook加载代码notebook所以你光pip install d2l是不够的前面少了Anaconda环境、虚拟环境、PyTorch框架这三个环节后面必然报错。这也是为什么网上教程零零散散照着操作总对不上号。1.2 版本矩阵d2l与深度学习框架的对应关系《动手学深度学习》有两个主流版本对应的视频和代码环境。早期代码基于MXNetd2l版本是0.17.x后来PyTorch版成了主流d2l版本也迭代到了1.x和2.x。这里最关键的认知是d2l包的版本必须和PyTorch大版本兼容。我实测下来比较稳定的组合直接用下面这个表格说明组件推荐版本说明Anaconda2024.10及以上自带Python 3.11安装器选择64位Python虚拟环境3.10最稳的版本大多数依赖都有预编译轮子PyTorch2.x系列如2.1.2支持CUDA 11.8/CUDA 12.1CPU版也可以学习d2l1.0.3书中代码、测试环境基于该版本最不易出错Jupyternotebook 7.x配合核内环境运行notebook这里有个常见误区看到pip install d2l就默认装最新版结果最新版要求Python 3.11或者特定PyTorch版本反而和书里的代码不兼容。我的建议是学习阶段锁定版本别追求最新。为什么要用虚拟环境因为深度学习框架之间、不同项目之间经常有依赖冲突。比如项目A需要NumPy 1.26项目B需要NumPy 2.0如果你都装在base环境就只能在两个项目间反复卸载重装非常痛苦。conda虚拟环境就是给每个项目隔离出一套独立的Python和包集合。2. 安装前必须搞定的三件事Anaconda、虚拟环境与镜像源2.1 Anaconda安装版本与安装选项的正确选择Anaconda的安装本身不复杂但有几个细节直接影响后续使用下载渠道Anaconda官网下载速度慢是出了名的建议直接用清华镜像站的Anaconda安装包在Anaconda Archive目录下选择最新版。Windows系统选择Anaconda3-2024.10-1-Windows-x86_64.exe文件名带x86_64的是64位版本。安装路径务必使用全英文路径避免出现中文或空格。我曾经见过有人装在D:\软件\Anaconda下后面conda命令和Jupyter各种灵异报错改成D:\Anaconda后一切正常。安装选项Windows安装界面里会问是否把Anaconda加入系统PATH。这里我建议勾选Add Anaconda3 to my PATH environment variable这是新手最容易操作的方案。如果你以后会用Docker、多版本Python再考虑不加PATH、改用Anaconda Prompt的方案。安装完成后打开Anaconda PromptWindows或终端macOS/Linux输入conda --version确认输出如conda 24.x.x这一步验证通过再继续往下走。2.2 为什么一定要建虚拟环境在base环境直接装d2l不是不行但后续很容易把base环境搞乱。我的习惯是任何深度学习项目都先建独立环境conda create -n d2l python3.10这条命令创建了一个名为d2l的虚拟环境Python版本指定为3.10。实际操作中conda create可能会因为默认源下载太慢而卡住所以建议先配好镜像源再创建环境。环境创建好后要激活它conda activate d2l激活之后终端或命令行的开头会显示(d2l)前缀。这个前缀非常重要它提醒你现在所有pip和python命令都在d2l环境里执行。我排查过不少同学的报错最后发现就是没激活环境包装到了base环境自然import d2l失败。2.3 换镜像源解决下载慢问题的关键Anaconda默认从国外源下载动辄几十KB/s一个环境创建可能就要十分钟。解决办法是更换为清华TUNA镜像。Windows用户在自己的用户目录下创建或修改.condarc文件Linux/macOS同理写入如下配置channels: - defaults show_channel_urls: true default_channels: - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2 custom_channels: conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud配置完成后建议执行conda clean -i清空索引缓存然后创建虚拟环境就会快很多。注意PyTorch的CPU版没必要走conda源后面我习惯用pip安装pip源也换到清华镜像双管齐下最省心pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple3. d2l包安装的完整操作链路含版本选择逻辑3.1 先装PyTorch再装d2l为什么顺序不能反在激活d2l环境后第一步不是pip install d2l而是先安装PyTorch。因为d2l只是个高层次的封装库它的底层依赖是PyTorch。如果先装d2l再装PyTorchd2l的依赖检查会找不到torch即便装上也要被迫重新解析依赖关系容易出现版本错乱。PyTorch官方提供了一条根据你的系统自动生成的安装命令这里以CPU版为例pip install torch torchvision torchaudio如果你用的是带NVIDIA GPU的电脑想用GPU加速训练则需要去PyTorch官网选择对应的CUDA版本典型的命令是pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118这里cu118表示CUDA 11.8版本。GPU环境需要提前安装好NVIDIA显卡驱动然后PyTorch会携带对应的CUDA runtime不再需要单独安装完整的CUDA Toolkit。初学者如果暂时没有GPU直接用CPU版即可前几章的代码在CPU上跑完全没问题只是CNN那几章训练会慢一些。提示安装完成后可以用python -c import torch; print(torch.__version__)验证PyTorch是否安装成功。能输出版本号说明框架层没问题。3.2 用pip安装d2l包版本锁定的选择逻辑PyTorch安装成功后再安装d2lpip install d2l1.0.3为什么要明确写出1.0.3因为《动手学深度学习》第二版的中文代码在编写和测试时锁定的就是d2l 1.0.3版本。如果你直接pip install d2l装到的最新版本可能接口有变化书里的代码运行时会出现意想不到的API报错。与其排查新版本的不兼容不如一开始就锁定版本跟着书里走。如果你的网络不太稳定在pip安装时经常超时推荐加两个参数pip install d2l1.0.3 -i https://pypi.tuna.tsinghua.edu.cn/simple --timeout 120其中--timeout 120是让pip每次请求的等待时间延长到120秒。我曾经在默认30秒超时的情况下反复报ReadTimeoutError换成120秒后一次通过。d2l包安装时依赖matplotlib、requests、pandas等库pip会自动解析安装。如果这些依赖包你已经装过安装会非常快。3.3 安装Jupyter Notebook让代码跑起来d2l-zh仓库里的学习资料大部分是.ipynb格式的Jupyter Notebook所以还需要一个能运行notebook的环境。Anaconda自带Notebook但要注意base环境的Jupyter不会自动识别你在d2l虚拟环境里安装的包。解决方法有两个一是激活d2l环境后在环境内部安装jupyterconda install jupyter pip install jupyter二是在d2l环境里手动安装ipykernel然后让Jupyter识别这个内核conda activate d2l pip install ipykernel python -m ipykernel install --user --name d2l --display-name d2l第二条命令的意思是把当前环境注册成Jupyter的一个内核以后打开Jupyter Notebook新建notebook时内核列表里就会有一个叫d2l的选项。记住一定要选对这个内核否则notebook里import d2l又会报模块不存在。4. 验证安装跑起Jupyter运行第一个深度学习示例4.1 导入级验证用两行命令确认环境可用装完别急着打开notebook先做一次导入级验证。在激活d2l环境的终端里依次执行python -c import torch; print(torch.__version__) python -c import d2l; print(d2l.__version__) python -c import d2l; print(d2l.torch.nn)第一条验证PyTorch版本第二条验证d2l是否导入成功第三条稍微进阶一点检查d2l封装的PyTorch模块是否存在。如果三条都正常输出说明你的安装链路基本没问题。我在自己电脑上实测时输出是这样的2.1.2 1.0.3 class module看到这个结果就可以放心进入Jupyter了。4.2 跑通一个真实示例线性回归的完整代码验证环境最好的方式是直接跑一个书里的真实示例。以线性回归为例在Jupyter里新建notebook选择名为d2l的内核输入下面的代码并运行import torch from d2l import torch as d2l # 生成人工数据集y 2 * x 1 噪声 true_w torch.tensor([2.0]) true_b torch.tensor([1.0]) features, labels d2l.synthetic_data(true_w, true_b, 1000) # 查看数据形状 print(features.shape, labels.shape) d2l.set_figsize() d2l.plt.scatter(features[:, 0].detach().numpy(), labels.detach().numpy(), s1) d2l.plt.show()如果这一连串代码都能正常执行并弹出散点图那么你的d2l-zh环境已经完全可用了。这里d2l.synthetic_data就是d2l包封装好的数据生成函数d2l.plt是它对matplotlib的二次封装set_figsize则统一设置了图片尺寸。新手看到这些API可能会觉得陌生但它们就是后续每章代码的基础跑通这个示例之后再看书里的其他代码就不会慌了。如果散点图没有弹出来而是提示plt.show()没有反应多半是matplotlib的后端配置问题。可以在notebook里加一行import matplotlib matplotlib.use(TkAgg)Windows系统如果还不行就把matplotlib卸载重装一次pip install --upgrade --force-reinstall matplotlib。4.3 运行notebook前的一个小习惯先配好工作目录很多同学直接双击下载的.ipynb文件结果Jupyter没有权限或找不到当前目录加载失败。建议先把d2l-zh仓库的代码克隆或下载到本地重命名为d2l-zh放在一个全英文路径下然后在Anaconda Prompt中执行cd D:\workspace\d2l-zh jupyter notebook这样Jupyter启动后的根目录就是你的代码目录notebook里涉及到的相对路径引用都不会出错。我见过一种典型报错FileNotFoundError: data/...就是因为notebook的当前工作目录和代码目录不一致而根本原因正是Jupyter启动目录不对。5. 高频报错逐条拆解从报错信息反推根因这一节是本篇的重点。我在实际辅导同学的过程中把遇到过的报错归纳成六类每类下面给出报错特征、根因分析和解决方法你可以直接对着自己的报错信息查。5.1 ModuleNotFoundError: No module named d2l这是出现频率最高的一种报错字面意思是找不到d2l模块。根因无非三种d2l压根没安装d2l装到了别的环境当前运行的Python是系统自带的Python而不是Anaconda环境里的Python排查方法也简单。首先确认环境里有没有包conda activate d2l pip list | findstr d2lmacOS/Linux下把findstr换成grep如果没有输出任何d2l相关信息说明没装重新执行pip install d2l1.0.3。如果有输出但import d2l还是报错就进一步确认当前Python路径python -c import sys; print(sys.executable)正常情况下这个路径应该指向你Anaconda安装目录下的envs\d2l\python.exe。如果路径指向了系统自带Python或Anaconda的base环境说明环境没有激活成功。Windows下尤其容易出现这个问题——在Anaconda Prompt里conda activate d2l之后如果终端还停留在原来的目录有时会误以为环境没激活其实只要看命令行前缀有没有变成(d2l)就行。5.2 pip install d2l时网络卡住ReadTimeoutError与镜像源典型报错信息类似WARNING: Retrying (Retry(total0)) after connection broken by ReadTimeoutError Could not find a version that satisfies the requirement d2l这个根因很明确网络从官方PyPI下载包太慢导致pip请求超时。解决办法就是前面提到的清华源加超时参数pip install d2l1.0.3 -i https://pypi.tuna.tsinghua.edu.cn/simple --timeout 120 --retries 5除了超时还有一种情况是Could not find a version。这通常不是网络问题而是你要安装的d2l版本在PyPI上不存在多半是因为版本号写错了。比如我之前写pip install d2l1.0.2但PyPI上的d2l版本列表里并没有1.0.2只有1.0.0、1.0.1等pip就会报找不到。解决方法是查询PyPI上到底有哪些版本pip index versions d2l然后选一个存在的版本安装。5.3 CondaHTTPError / 创建虚拟环境失败的解法创建虚拟环境时常见的报错是CondaHTTPError: HTTP 000 CONNECTION FAILED for url https://repo.anaconda.com/pkgs/main/...这同样是网络问题。conda默认从国外源下载Python解释器和依赖一旦网络不通创建环境就会失败。解决办法就是前面讲的配置.condarc文件里的清华源。配置完成后检查一下是否生效conda config --show channels然后重新执行conda create -n d2l python3.10 -y附加一个Windows下的奇坑如果你的用户目录名有中文.condarc放在C:\Users\张三下conda读取时可能因为路径编码问题报未知错误。遇到这种情况把Anaconda安装目录或用户目录改成英文用户名是最好的选择否则即使配好源后续很多工具也会有兼容性问题。5.4 OSError: [WinError 5] 拒绝访问 / 权限问题Windows系统下安装Anaconda或pip安装包时有时会遇到OSError: [WinError 5] Access is denied或者安装Anaconda时报Anaconda3 is not installed in this location, and you do not have sufficient permissions。这类问题基本都是权限不足。Anaconda默认装在C:\ProgramData\Anaconda3这类系统保护目录下pip往里面写文件时会被Windows拦截。我一般建议改进两个层面一是安装Anaconda时选择Install for me only而不是Install for All Users。前者装到用户目录如C:\Users\你的名字\anaconda3权限问题少很多。二是运行Anaconda Prompt时右键选择以管理员身份运行。注意管理员权限也不是万能的如果你之前用普通权限装了一些包再切管理员权限去装其他包可能会出现包的元数据都写到用户目录里、但实际运行时找不到的情况。最干净的方案是卸载重装Anaconda到用户目录一条路走到底。还有一个小概率情况杀毒软件或Windows Defender实时保护会锁住一些Python进程生成的文件导致OSError: [WinError 5]。如果重装之后问题依旧可以临时关闭实时保护再安装装完再重新开启。5.5 NumPy版本过高/过低导致的属性报错d2l依赖NumPy但NumPy 2.0发布后很多旧版库和它出现了不兼容典型报错是AttributeError: module numpy has no attribute bool或者运行1.x时代的d2l代码时报AttributeError: numpy.float64 object has no attribute is_integer这类问题本质上是NumPy API变更引起的兼容性断裂。d2l 1.0.3在开发时依赖的NumPy还是1.x版本如果你装环境时pip自动拉取到了NumPy 2.x就有概率踩坑。解决方法是把NumPy锁到1.24.xpip install numpy1.24.4安装完成后用python -c import numpy; print(numpy.__version__)确认版本。需要注意的是先装d2l再锁定NumPy的顺序很关键因为如果先降NumPy再装d2ld2l可能会把NumPy再升回去。先装d2l和torch最后统一锁NumPy版本这样最省心。5.6 Jupyter内核不显示、CUDA内存不足、Matplotlib中文乱码这三类问题在Notebook阶段高频出现我放在一起说明。Jupyter内核不显示d2l打开Notebook新建文件时内核列表里没有d2l。这通常是因为没在d2l环境里注册ipykernel执行下面的命令即可conda activate d2l pip install ipykernel python -m ipykernel install --user --name d2l --display-name d2l注册之后如果Jupyter是开着的需要重启Jupyter才能看到新的内核。CUDA out of memory跑CNN之类较大模型时GPU显存爆了。如果你用的是GPU环境解决办法是把batch size调小比如从256调成64或者把图像尺寸缩小。如果你的环境根本没有GPU那句CUDA out of memory同样可能出现——某些版本的PyTorch默认把模型加载到GPU但显存不足。我建议初学者在不了解的情况下先把代码里的.to(cuda)去掉强制用CPU跑先保证流程跑通。Matplotlib中文乱码绘图时中文显示成方块。这是因为matplotlib默认字体不支持中文。在代码最前面加上import matplotlib.pyplot as plt plt.rcParams[font.sans-serif] [SimHei, Microsoft YaHei, PingFang SC] plt.rcParams[axes.unicode_minus] FalseWindows系统一般设置SimHei就能解决macOS设置PingFang SCLinux可能要安装中文字体。我把上述报错汇总成一张速查表方便你对照报错信息根因核心解决动作ModuleNotFoundError: No module named d2l未安装/环境未激活/装错环境conda activate d2l后pip install d2l1.0.3ReadTimeoutError / Could not find a version网络慢、版本号错误使用清华源 --timeout 120检查PyPI版本列表CondaHTTPError: HTTP 000conda源网络不通配置清华.condarc镜像源OSError: [WinError 5] 拒绝访问安装权限不足安装到用户目录管理员身份运行PromptAttributeError: module numpy no attribute...NumPy 2.x不兼容pip install numpy1.24.4Jupyter内核列表没有d2lipykernel未注册在d2l环境执行python -m ipykernel installCUDA out of memorybatch size过大或误用GPU调小batch_size或用CPU跑中文显示为方块matplotlib字体不支持中文配置rcParams[font.sans-serif]注意如果报错信息不在上表中先不要慌。把报错的关键词复制到搜索引擎里搜一下重点看stack overflow或GitHub issues里的回复。大多数d2l相关报错都有人踩过坑并给出了解决方案。6. 把环境玩明白版本锁定与环境备份的实用技巧6.1 用conda env export备份可复现环境环境配置好后强烈建议做一个环境快照方便以后复现或迁移conda activate d2l conda env export d2l_environment.yaml当你换了新电脑或者哪天环境被自己搞坏了用下面的命令一键重建conda env create -f d2l_environment.yaml这一个习惯能省下大量重装时间。我自己在写深度学习实验时每个项目都会固定一份environment.yaml这样即便三个月后回看旧项目也能精准还原当时的软件环境不会出现代码在你这儿能跑在我这儿报错的尴尬。6.2 不要频繁升级d2l和PyTorch这是我踩过的坑值得专门提醒。初学者喜欢装最新的东西但深度学习框架的API变动非常频繁。今天torch 2.2里某个函数还能用明天升级到2.3可能就标了废弃d2l包更明显不同小版本之间封装的函数名都会调整。所以我在学习阶段的做法是只要环境能用绝不轻易升级。如果你想体验新版功能就新建一个环境去试不要动正在学习用的d2l环境。这个习惯能帮你避开大量无意义的报错。6.3 实测环境配置速查清单最后给出一份我们实验室常用的开工配置清单配合前面的命令直接抄作业即可1. conda create -n d2l python3.10 -y 2. conda activate d2l 3. pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 或 pip install torch torchvision torchaudioCPU版 4. pip install d2l1.0.3 -i https://pypi.tuna.tsinghua.edu.cn/simple 5. pip install numpy1.24.4 6. pip install jupyter ipykernel 7. python -m ipykernel install --user --name d2l --display-name d2l 8. cd d2l-zh代码目录 jupyter notebook我在多台Windows、macOS、Ubuntu机器上按这个流程操作过除了个别网络问题的变种外几乎都能一次性成功。如果你按照本文步骤操作完还有问题欢迎把报错信息贴到评论区我会根据具体报错帮你分析。7. 我在多次安装d2l环境后的体会安装d2l-zh这套环境最核心的一点不是记住命令而是理解环境隔离、版本匹配、镜像加速这三个逻辑。命令只是表象逻辑相通之后不管以后安装其他深度学习框架还是部署自己的项目都会顺畅很多。就我自己而言第一次安装时也曾在网络超时和NumPy报错之间反复折腾最后发现问题就是版本锁定没做好。从那以后我养成了一个习惯每装一个包先确认安装在哪个环境、对应哪个版本然后及时把环境导出一份yaml存档。看似多花两三分钟实际是省下未来几天的时间。如果你之后学到卷积神经网络那几章发现CPU训练太慢再考虑配置GPU版PyTorch也不迟。环境配置这件事最怕在还没开始学习时就把热情耗尽。跟着上面的步骤一步步来环境一次配好后面专注啃书本内容就好。