QGIS 报错 DLL load failed while importing _gdal 解决方法
发布于 更新于
ImportError: DLL load failed while importing _gdal 会导致在 Windows 上 QGIS 内运行 from osgeo import gdal 的任何 Python 失败，包括处理工具箱。PATH 中还有另一个 GDAL 副本排在 QGIS 版本之前，因此请从 PATH 中移除这些非 QGIS 文件夹，然后注销 Windows 并重新登录。在大多数机器上，这就是完整修复方法，下面四种方法覆盖其余情况。
ImportError: DLL load failed while importing _gdal: The specified module could not be found.
On Windows, with Python >= 3.8, DLLs are no longer imported from the PATH.
If gdalXXX.dll is in the PATH, then set the USE_PATH_FOR_GDAL_PYTHON=YES environment variable
to feed the PATH into os.add_dll_directory().
GDAL 在 3.7.0 版本中移除了这三行提示，因此在当前安装中您只会看到第一行。有些机器上的错误会变一个词，但原因相同：
ImportError: DLL load failed while importing _gdal: The specified procedure could not be found.
大多数人从未读过这两种错误文本。他们看到的通常是 QGIS 日志消息面板（Log Messages）中的一行错误，以及一个空无一物的“数据处理”菜单：
Couldn't load plugin 'processing'
适用于 Windows、QGIS 3.16 及更高版本，以及任何运行 from osgeo import gdal 的 Python 3.8 或更高版本。
快速修复
列出 PATH 中包含 GDAL DLL 的所有文件夹
从“开始”菜单中的 QGIS 文件夹打开 OSGeo4W Shell，然后运行以下命令。它会重复 GDAL 自己的逻辑：
python -c "import os,glob;print('\n'.join(p for p in os.environ['PATH'].split(';') if p and (glob.glob(os.path.join(p,'gdal*.dll')) or glob.glob(os.path.join(p,'libgdal*.dll')))))"
阅读第一行。这就是 GDAL 采用的文件夹，它应该位于 QGIS 安装目录中。保留完整输出，下面的每种修复方法都会用到它。
删除不是 QGIS 的条目
Anaconda、Miniconda、第二个 QGIS 或 OSGeo4W 安装、其他 GIS 套件都可能造成问题。打开“开始”，输入“环境变量”，打开“编辑系统环境变量”，然后依次进入“环境变量”、“Path”，并删除这些条目。注销 Windows 并重新登录。
从 QGIS 自己的快捷方式启动 QGIS
不要从已经运行过其他环境 activate 脚本的 shell 启动。一个将 gdal-dev 路径放在第一位的 shell，会直接把它交给 QGIS。
检查修复是否成功
在 QGIS 中依次打开 插件 > Python 控制台（Plugins > Python Console），并运行：
from osgeo import gdal
print(gdal.__version__)
如果上方没有 traceback，且显示了版本号，就表示正确的 DLL 已加载。也请打开“数据处理”菜单，因为只要 processing 插件能够导入 GDAL，工具箱就会恢复。“数据处理”菜单为空，表示问题仍未解决。
修复方法 2：在 QGIS 环境中运行脚本
第 1 步完全没有输出。PATH 中没有任何文件夹包含 GDAL DLL，因此没有任何内容被注册。这通常发生在普通的 python.exe 或 PyCharm 的运行配置在 QGIS 环境之外启动时。请改为在 OSGeo4W Shell 中运行脚本，或通过 QGIS bin 文件夹中的 python-qgis.bat 运行。在长期发行版（LTR）安装中，该文件名为 python-qgis-ltr.bat。这两个文件都会在 Python 启动前注册正确的 DLL 文件夹。
如果错误没有变化，请转到修复方法 3。
修复方法 3：修复半升级的 OSGeo4W 安装
第 1 步输出了多行，并且它们全部位于同一个 OSGeo4W 树中。您同时保留了升级过程中留下的 gdal 和 gdal-dev，而升级过程并未完成。重新运行 OSGeo4W 安装程序并重新安装 gdal 和 qgis 软件包，或者使用独立安装程序重新安装 QGIS。后者是最快的解决方式。
如果错误没有变化，请转到修复方法 4。
修复方法 4：设置 USE_PATH_FOR_GDAL_PYTHON
第 1 步输出了一行，是 QGIS 的路径，但导入仍然失败。现在可以尝试设置该变量，仅限现在。在 QGIS 中依次打开 设置 > 选项 > 系统（Settings > Options > System），进入“环境”分组（Environment）。勾选自定义变量选项（custom variables），添加以下名称和值，然后重启 QGIS：
USE_PATH_FOR_GDAL_PYTHON=YES
它只对少数用户有帮助，原因见“为什么会发生”。
如果错误没有变化，请转到修复方法 5。
修复方法 5：每个 conda 环境只保留一个 GDAL
如果 GDAL 来自 conda，请仅在全新环境中从 conda-forge 获取它，并且不要在同一环境中混入 pip GDAL wheel。一个渠道，一个副本。
如果错误没有变化，请将下面三项内容发给我。
为什么会发生
Python 3.8 停止为扩展 DLL 搜索 PATH。GDAL 在 osgeo/__init__.py 中对此进行了处理。当 USE_PATH_FOR_GDAL_PYTHON 未设置时，GDAL 按顺序读取 PATH，使用 os.add_dll_directory() 注册第一个包含 gdal*.dll 或 libgdal*.dll 的文件夹，然后停止搜索。因此，PATH 中最早出现的 GDAL 会胜出。如果该副本不是 QGIS 的版本，它的 DLL 就无法匹配 QGIS 构建时使用的 _gdal 模块。
设置该变量会扩大搜索范围，而不是缩小范围，因为 GDAL 随后会注册 PATH 中的每个文件夹，并且完全不使用 glob。因此，错误消息过去打印的那一行几乎帮不到任何人。
我们的 AI Segmentation 插件通过 QGIS 自带的 GDAL 读取栅格，不安装自己的 GDAL，因此上面的导入成功后，它也会立即正常工作。我们为 QGIS 构建的其他内容位于 QGIS AI 页面。
仍然无法解决？
请发送三项内容：您的 QGIS 版本、完整 traceback，以及快速修复第 1 步中的 PATH 检查输出。我的邮箱是 stephane.barbot@terra-lab.ai。该输出的第一行通常就足以判断您属于五种情况中的哪一种。
常见问题
为什么我的错误中没有提到 USE_PATH_FOR_GDAL_PYTHON？
GDAL 在 3.7.0 版本中移除了那三行提示，因此当前版本只会打印第一行，不会打印其他内容。原因并没有因此改变。在 3.6 上采用的修复方法仍然相同。
设置 USE_PATH_FOR_GDAL_PYTHON=YES 能解决问题吗？
很少能，而且它被列为修复方法 4 而不是修复方法 1，是有原因的。该变量会让 GDAL 注册 PATH 中的每个文件夹，而不是只注册第一个包含 GDAL DLL 的文件夹。它扩大了搜索范围，并不会将搜索指向 QGIS。只有当 PATH 显示一个 GDAL 文件夹且导入仍然失败时，才尝试它。
为什么我的处理工具箱会同时消失？
processing 插件会导入 GDAL，因此它无法加载，QGIS 会在日志消息面板（Log Messages）中写入 "Couldn't load plugin 'processing'"。导入成功后，工具箱会自行恢复，因此这是判断修复是否生效的最快方式。
如果 traceback 显示的是 _C 而不是 _gdal，该怎么办？
那是另一个模块，需要另一种修复方法。它有自己的文章：DLL load failed while importing _C。
