1. 为什么你需要这份d2l避坑指南第一次打开李沐老师的《动手学深度学习》时我和大多数初学者一样兴奋。但当我尝试运行书中的代码示例时现实给了我一记重拳——那个看似简单的import d2l语句居然报错了如果你也遇到过类似的情况那么这份指南就是为你准备的。d2l库是《动手学深度学习》的配套工具库它包含了书中所有代码示例所需的辅助函数和数据集下载工具。但在实际安装和使用过程中Windows、Mac和Linux用户都可能遇到各种环境问题。最常见的就是ImportErrorPython找不到d2l模块PermissionError数据目录创建失败路径解析问题相对路径在不同操作系统表现不一致我在三个不同平台Windows 10、Ubuntu 20.04和macOS Monterey上测试过d2l的安装过程发现即使是相同的安装步骤在不同系统上也可能产生完全不同的结果。比如Windows用户经常卡在权限问题上而Linux用户则更容易遇到Python路径配置问题。2. 全平台安装指南2.1 基础安装方法最稳妥的安装方式是通过pip直接安装。打开你的终端Windows用户建议使用Anaconda Prompt运行以下命令pip install d2l这个命令会自动从PyPI下载最新版本的d2l当前是0.17.6版。但如果你遇到下载速度慢的问题可以尝试清华镜像源pip install d2l -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后不要急着import先确认安装是否成功pip show d2l这个命令会显示d2l的安装路径和版本信息。如果这里没有输出说明安装可能失败了。2.2 常见安装问题排查问题1安装成功但import报错这种情况通常是因为你的Python环境有多个解释器。比如你同时安装了Anaconda和系统Python而d2l可能装在了另一个环境中。解决方法which python # Linux/Mac where python # Windows确认当前使用的Python解释器路径然后使用绝对路径安装/usr/local/bin/python3 -m pip install d2l问题2SSL证书错误某些网络环境下可能会出现SSL证书验证失败。临时解决方案不推荐长期使用pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org d2l3. IDE配置技巧3.1 VSCode设置如果你在VSCode中遇到Import could not be resolved的红色波浪线虽然代码能运行这是因为VSCode的Python插件需要额外配置。按下Ctrl,打开设置搜索python.analysis.extraPaths添加d2l的安装路径通过pip show d2l获取。3.2 PyCharm用户注意PyCharm有时会自作聪明地创建虚拟环境导致安装的包不在当前项目环境中。解决方法打开File Settings Project Python Interpreter确认使用的是正确的解释器点击号直接搜索安装d2l4. 数据目录权限问题详解4.1 Windows权限问题Windows系统对Program Files等目录有严格的写入限制。当你看到类似这样的错误PermissionError: [WinError 5] 拒绝访问。: ..\\data这是因为代码尝试在受保护目录创建数据文件夹。解决方法不是使用管理员权限不安全而是修改数据存储位置。找到书中创建目录的代码通常在utils.py中将其改为import os data_dir os.path.join(os.path.expanduser(~), d2l_data) os.makedirs(data_dir, exist_okTrue)这样数据会保存在用户主目录下的d2l_data文件夹避开系统保护区域。4.2 Linux/Mac的权限处理在Unix-like系统中你可能需要手动设置目录权限chmod -R 755 ~/d2l_data如果你使用Docker容器运行代码还需要注意volume挂载权限VOLUME /home/user/d2l_data RUN chown user:user /home/user/d2l_data5. 实战中的高级技巧5.1 离线安装方案有些实验室环境无法连接外网这时可以在一台能上网的机器上先下载好pip download d2l -d ./d2l_packages然后把整个d2l_packages文件夹拷贝到离线环境使用以下命令安装pip install --no-index --find-links./d2l_packages d2l5.2 版本兼容性问题《动手学深度学习》的不同版本可能需要特定版本的d2l库。如果你使用的是纸质书建议查看书末的版本说明。一般来说第一版 → d2l 0.14.x第二版 → d2l 0.17.x可以通过指定版本号安装pip install d2l0.17.65.3 Jupyter Notebook集成如果你在Jupyter中运行代码遇到问题可能是内核选择错误。首先确认import sys print(sys.executable)输出的Python路径应该与你安装d2l的环境一致。如果不一致在Notebook中运行!{sys.executable} -m pip install d2l6. 自定义d2l功能d2l库的源码其实非常值得学习。我建议将它的源代码下载到本地git clone https://github.com/d2l-ai/d2l-zh.git然后修改PYTHONPATH环境变量直接使用本地版本export PYTHONPATH/path/to/d2l-zh:$PYTHONPATH这样你可以自由修改d2l的实现比如添加新的可视化函数或数据集支持。我在实际项目中就扩展了它的进度条显示功能加上了预估剩余时间。遇到特别棘手的问题时不妨直接查看d2l的GitHub仓库的issue区。我遇到的几个奇怪bug都是在那里找到的解决方案。比如有一个Windows特有的路径问题最终发现是因为Python的os.path在不同系统处理反斜杠的方式不同改用pathlib库就完美解决了。
李沐《动手学深度学习》d2l——从安装到实战避坑指南
发布时间：2026/7/9 12:35:44
1. 为什么你需要这份d2l避坑指南第一次打开李沐老师的《动手学深度学习》时我和大多数初学者一样兴奋。但当我尝试运行书中的代码示例时现实给了我一记重拳——那个看似简单的import d2l语句居然报错了如果你也遇到过类似的情况那么这份指南就是为你准备的。d2l库是《动手学深度学习》的配套工具库它包含了书中所有代码示例所需的辅助函数和数据集下载工具。但在实际安装和使用过程中Windows、Mac和Linux用户都可能遇到各种环境问题。最常见的就是ImportErrorPython找不到d2l模块PermissionError数据目录创建失败路径解析问题相对路径在不同操作系统表现不一致我在三个不同平台Windows 10、Ubuntu 20.04和macOS Monterey上测试过d2l的安装过程发现即使是相同的安装步骤在不同系统上也可能产生完全不同的结果。比如Windows用户经常卡在权限问题上而Linux用户则更容易遇到Python路径配置问题。2. 全平台安装指南2.1 基础安装方法最稳妥的安装方式是通过pip直接安装。打开你的终端Windows用户建议使用Anaconda Prompt运行以下命令pip install d2l这个命令会自动从PyPI下载最新版本的d2l当前是0.17.6版。但如果你遇到下载速度慢的问题可以尝试清华镜像源pip install d2l -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后不要急着import先确认安装是否成功pip show d2l这个命令会显示d2l的安装路径和版本信息。如果这里没有输出说明安装可能失败了。2.2 常见安装问题排查问题1安装成功但import报错这种情况通常是因为你的Python环境有多个解释器。比如你同时安装了Anaconda和系统Python而d2l可能装在了另一个环境中。解决方法which python # Linux/Mac where python # Windows确认当前使用的Python解释器路径然后使用绝对路径安装/usr/local/bin/python3 -m pip install d2l问题2SSL证书错误某些网络环境下可能会出现SSL证书验证失败。临时解决方案不推荐长期使用pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org d2l3. IDE配置技巧3.1 VSCode设置如果你在VSCode中遇到Import could not be resolved的红色波浪线虽然代码能运行这是因为VSCode的Python插件需要额外配置。按下Ctrl,打开设置搜索python.analysis.extraPaths添加d2l的安装路径通过pip show d2l获取。3.2 PyCharm用户注意PyCharm有时会自作聪明地创建虚拟环境导致安装的包不在当前项目环境中。解决方法打开File Settings Project Python Interpreter确认使用的是正确的解释器点击号直接搜索安装d2l4. 数据目录权限问题详解4.1 Windows权限问题Windows系统对Program Files等目录有严格的写入限制。当你看到类似这样的错误PermissionError: [WinError 5] 拒绝访问。: ..\\data这是因为代码尝试在受保护目录创建数据文件夹。解决方法不是使用管理员权限不安全而是修改数据存储位置。找到书中创建目录的代码通常在utils.py中将其改为import os data_dir os.path.join(os.path.expanduser(~), d2l_data) os.makedirs(data_dir, exist_okTrue)这样数据会保存在用户主目录下的d2l_data文件夹避开系统保护区域。4.2 Linux/Mac的权限处理在Unix-like系统中你可能需要手动设置目录权限chmod -R 755 ~/d2l_data如果你使用Docker容器运行代码还需要注意volume挂载权限VOLUME /home/user/d2l_data RUN chown user:user /home/user/d2l_data5. 实战中的高级技巧5.1 离线安装方案有些实验室环境无法连接外网这时可以在一台能上网的机器上先下载好pip download d2l -d ./d2l_packages然后把整个d2l_packages文件夹拷贝到离线环境使用以下命令安装pip install --no-index --find-links./d2l_packages d2l5.2 版本兼容性问题《动手学深度学习》的不同版本可能需要特定版本的d2l库。如果你使用的是纸质书建议查看书末的版本说明。一般来说第一版 → d2l 0.14.x第二版 → d2l 0.17.x可以通过指定版本号安装pip install d2l0.17.65.3 Jupyter Notebook集成如果你在Jupyter中运行代码遇到问题可能是内核选择错误。首先确认import sys print(sys.executable)输出的Python路径应该与你安装d2l的环境一致。如果不一致在Notebook中运行!{sys.executable} -m pip install d2l6. 自定义d2l功能d2l库的源码其实非常值得学习。我建议将它的源代码下载到本地git clone https://github.com/d2l-ai/d2l-zh.git然后修改PYTHONPATH环境变量直接使用本地版本export PYTHONPATH/path/to/d2l-zh:$PYTHONPATH这样你可以自由修改d2l的实现比如添加新的可视化函数或数据集支持。我在实际项目中就扩展了它的进度条显示功能加上了预估剩余时间。遇到特别棘手的问题时不妨直接查看d2l的GitHub仓库的issue区。我遇到的几个奇怪bug都是在那里找到的解决方案。比如有一个Windows特有的路径问题最终发现是因为Python的os.path在不同系统处理反斜杠的方式不同改用pathlib库就完美解决了。
