Python3.8环境导入GDAL报DLL加载失败找不到指定程序问题

问题现象 #

安装GDAL库后导入时持续触发ImportError：

DLL load failed while importing _gdal: The specified procedure was not found.

当前运行环境信息：

Python 3.8.10 (tags/v3.8.10:3d8993a, May  3 2021, 11:48:03) [MSC v.1928 64 bit (AMD64)] on win32

安装使用的wheel包为GDAL-3.3.3-cp38-cp38-win_amd64.whl，来自第三方预编译Python包站点。
待确认问题：

• 报错是否由wheel版本与环境不匹配导致
• 若为版本适配问题，如何查找匹配当前环境的正确安装包

测试用Basemap示例代码：

from asyncio.windows_events import NULL
from traceback import print_tb
from osgeo import gdal 
from numpy import meshgrid
from numpy import linspace

map = Basemap(projection='tmerc', 
              lat_0=0, lon_0=3,
              llcrnrlon=1.819757266426611, 
              llcrnrlat=41.583851612359275, 
              urcrnrlon=1.841589961763497, 
              urcrnrlat=41.598674173123)

ds = gdal.Open("C:/elevation.tif")
data = ds.ReadAsArray()

x = linspace(0, map.urcrnrx, data.shape[1])
y = linspace(0, map.urcrnry, data.shape[0])

xx, yy = meshgrid(x, y)

cs = map.contour(xx, yy, data, range(400, 1500, 100), cmap = plt.cm.cubehelix)
plt.clabel(cs, inline=True, fmt='%1.0f', fontsize=12, colors='k')

plt.show()

原因判定与解决方案 #

这个报错本质是GDAL核心动态链接库加载时找不到对应函数入口，你选择的cp38、win_amd64标识的包从命名规则上是匹配Python3.8 64位环境的，触发问题的常见原因和对应处理方式如下：

• 环境路径冲突：如果本地安装过QGIS、OSGeo4W或者独立部署的GDAL，这些软件自带的GDAL动态库路径如果被加入系统PATH，优先级会高于pip安装的GDAL依赖路径，加载时会出现版本串扰。处理方式：要么在无其他GDAL路径干扰的干净Python虚拟环境中安装测试，要么调整系统PATH顺序，将Python对应site-packages下的osgeo目录路径优先级调高。
• 运行库依赖缺失：Python3.8是基于MSC v.1928（Visual Studio 2019）编译的，需要对应版本的64位VC++运行库支持，若本地未安装对应运行库，也会触发DLL加载失败，直接安装对应版本的VC Redistributable即可。
• 关联库版本不匹配：如果同时安装了pyproj、fiona、basemap这类依赖GDAL的地理空间库，若这些库的编译版本和GDAL版本不对应，也会引发DLL冲突，需要选择同一编译版本的关联库安装。

适配包选择方法 #

选择预编译GDAL wheel包时只需要核对三个匹配项即可：

1. Python版本匹配：包名中cp后跟随的版本号要和本地Python大版本一致，比如Python3.8对应cp38，不要选cp37、cp39的包
2. 系统架构匹配：64位Windows系统选win_amd64包，32位系统选win32包，不要跨架构安装
3. 依赖版本匹配：如果需要搭配其他地理空间相关库使用，尽量选择同一发布者、同一GDAL大版本编译的包，避免依赖冲突

额外提示：你提供的测试代码存在缺失导入的问题，缺少from mpl_toolkits.basemap import Basemap和import matplotlib.pyplot as plt两个导入语句，即便GDAL安装成功，直接运行也会触发NameError。

内容的提问来源于stack exchange，提问作者Weiss