★ FEATURED ARTICLE 简介为 Windows 7 64 位平台下的 Python 2.7 用户提供 GDAL 安装全攻略内容涵盖 Visual Studio 2010、GEOS 3.3.8 等依赖项准备以及两种安装思路一是基于 core 代码配合 swig/python 自编译二是直接下载官方 msi 安装。资源包为单个 docx 文件体积约 95KB文字精炼聚焦安装过程中最常见的错误与排障方法比如 swig.exe 缺失、VS2010 下 Vcvarsall.bat 无法找到、import gdal 时提示 DLL load failed 等并给出添加环境变量 Path、设置 VS90COMNTOOLS 等具体操作。已有 628 人学习过适合刚接触地理空间库开发的用户参考能显著减少踩坑时间。1. 装完 GDAL 就报 DLL load failed这条报错值得先讲清楚Python 2.7 Win7 64 位平台装 GDAL十个人里至少有八个会在import gdal时撞上同一堵墙ImportError: DLL load failed: 找不到指定的模块。更折磨人的是这条报错在你用源码编译、用 msi 直装、甚至换 GDAL 1.9.2 / 1.11.0 时都会出现而且每次出现的时机都不一样——有时刚装完就报有时编译成功后第一次 import 才报。我前后折腾了两天把两条主流安装路线core 代码 swig 自编译、官方 msi 直装都完整走了一遍也把 swig.exe 缺失、Vcvarsall.bat 找不到、DLL 依赖解析失败这些坑逐个踩平。这篇就按我的实操顺序复盘每个报错的触发条件、根因在哪、怎么改才能过以及一套能套用到多数场景的快速定位方法。2. 源码编译路线nmake 报 swig.exe 不是内部或外部命令 的完整解决2.1 环境与版本选择VS2010、GEOS 3.3.8、GDAL 1.9.2 与 Python 2.7 的对应关系先说我这次的实际环境Win7 64 位机器Python 2.7Visual Studio 2010GEOS 3.3.8GDAL 用的是 1.9.2 的 core 压缩包。1.11.0 我也下载尝试过理论上同样适用只是重新配置时我又换回了老一点、网上资料更多的版本——在 Windows 上编译开源库资料多寡直接决定你踩坑的成本。GEOS 3.3.8 是 GDAL 在矢量几何运算上的可选依赖这里先装好避免后续编译某些功能模块时出现莫名其妙的头文件或符号缺失。这里必须先说清楚一个概念Python 版的 GDAL 本质上不是一个纯 Python 包而是一堆 C 扩展——site-packages/osgeo下的_gdal.pyd、_ogr.pyd才是真正干活的机器码。所以源码路线首要前提是机器上有一套可用的 C/C 编译链VS2010 就是干这个的。我建议你把 VS2010 装完整别只装命令行工具否则后面setup.py build阶段找不到完整工具链会引出另一类报错。2.2 进入 X64 兼容工具命令提示符并切换到 swig 目录这一步很多人第一眼就忽略了但它决定后续所有命令能不能用。不要在普通 cmd 里直接敲nmake那样 VS2010 的编译器环境变量INCLUDE、LIB、PATH根本没有注入当前会话。正确操作是右键单击“开始 所有程序 Microsoft Visual Studio 2010 Visual Tools Visual Studio X64 兼容工具命令提示符”选择“以管理员身份运行”。这个命令提示符会把 64 位编译工具链完整加载到当前 shell接下来的 nmake、cl.exe、链接器就都能找到了。打开后切换到 GDAL core 源码解压目录下的 swig 子目录我这边路径是cd C:\OGC\GDAL192\gdal-1.9.2\swig路径要替换成你实际解压的位置。注意 GDAL core 解压目录最好不要带空格Windows 下路径带空格会引出一串引号问题和脚本变量展开错误这是血泪经验。如果你之前把压缩包解压到了带空格的目录里建议直接挪走重来省得后面 makefile 里的路径拼接出错。2.3 执行 nmake /f makefile.vc python第一个报错是 swig.exe 不在 PATH进入 swig 目录后按 GDAL 编译文档执行这条命令nmake /f makefile.vc python我这次遇到的第一个错误就是swig.exe 不是内部或外部命令也不是可运行的程序或批处理文件。 NMAKE : fatal error U1077: swig.exe: 返回代码0x1这条报错的根因很好解释makefile.vc里的 python 目标依赖 swig 这个代码生成器来生成 Python 绑定用的 C 包装代码比如gdalconst_wrap.c但 GDAL 源码包本身并没有把 swig.exe 的二进制打进去。nmake 在执行到调用 swig.exe 那一步时发现系统 PATH 里找不到这个命令于是整条编译链中断。这跟“缺库”无关纯粹是构建工具缺失。解决办法是安装 swig建议装 2.10.0 版本并把 swig.exe 所在目录加入 PATHset PATHC:\Program Files\swigwin-2.10.0;%PATH%解释一下set PATH...把 swig 目录临时插到当前窗口环境变量最前面不影响系统全局设置分号是 Windows 路径分隔符。加完后重新执行nmake /f makefile.vc python如果提示不再报 swig.exe说明代码生成阶段已经通过。这里有个小提醒如果系统里还有别的 swig 版本注意版本别太老或太新老版本对 makefile 里-modern -new_repr这几个参数支持不全可能生成出编译不过的 C 代码。3. 编译后半程unable to find Vcvarsall.bat 与 setup.py 刷屏警告3.1 切换到 swig/python 子目录后python setup.py build 报错上一步 nmake 成功之后继续往 Python 绑定目录走cd python python setup.py build此时大概率会撞上第二个经典报错unable to find Vcvarsall.bat。我第一次看到这行时整个人是懵的——明明 VS2010 装得完整编译器也在怎么还找不到后来才明白这是 Python 2.7 的老毛病它官方是用 VS2008 编译的所以setup.py的 distutils 在定位编译器时写死的环境变量是VS90COMNTOOLS对应 VS2008 9.0。而我这台机器只装了 VS2010环境变量只有VS100COMNTOOLS对应 10.0distutils 按老名字找不到 vcvarsall.bat于是构建直接中止。网上有人给过一堆方案比如装 VS2008 Express或者手动拷贝 vcvarsall.bat都太绕了。在 VS2010 机器上最省事的做法是直接在命令行里做一个变量映射set VS90COMNTOOLS%VS100COMNTOOLS% python setup.py build python setup.py install第一行命令的意思是把 VS2010 工具链的安装目录“借”给VS90COMNTOOLS让 Python 2.7 的构建脚本以为自己找到的是 VS2008。VS2010 编译出的 C 扩展在 Python 2.7 下是可以正常加载的只要 VC 运行时环境没问题。网上还有方案推荐用 mingw 绕过这条限制我实际实验过失败了后面避坑章节会专门说这个。3.2 setup.py 一路刷屏的警告哪些可以无视哪些必须盯执行完上面两条命令后屏幕上会滚动大量编译提示和警告比如宏重定义、符号截断、C4996 之类。第一次看到满屏 warning 时我以为是哪里坏了逐条去查浪费了一个多小时。后来验证下来只要最后的install没有以error:结尾没有出现链接失败 LNK 级别的错误这些警告都不会影响最终产物。它们大多来自第三方头文件与编译器默认宏的碰撞属于“看着吓人、实则无害”。真正需要盯的是两件事一是 install 是否把包写进了 Python 的site-packages二是osgeo目录是否存在。可以这样验证python -c import osgeo这条命令不报错说明扩展包本体已经装进去了。但要注意这一步通过只代表“文件就位”不代表import gdal就一定能成功因为后面还有 DLL 依赖这个大坑等着你——也是整个安装过程中最迷惑人的一步。3.3 刚装完又见 ImportError: DLL load failed根因不在 Python 代码源码编译成功、扩展也装进 site-packages 后我迫不及待地在命令行敲了import gdal结果又被拍回原点ImportError: DLL load failed: 找不到指定的模块。这条报错最坑的地方在于它的调用栈很长先是gdal.py里的from osgeo.gdal import deprecation_warn再进到osgeo/__init__.py里的_gdal swig_import_helper()最后是imp.load_module(_gdal, ...)才抛出异常。第一次看你会以为是 gdal.py 有问题实际上真正失败的环节是 Python 加载_gdal.pyd这个 C 扩展时Windows 加载器必须把它的所有依赖 DLL 解析出来而gdal192.dll并不在 Python 进程的搜索路径里于是笼统地抛一句“找不到指定的模块”。这就是个典型的黑匣子报错信息指向 Python 文件根因却在外部的 DLL 搜索路径。解决方案就是把 GDAL 安装目录下的 bin 目录加进 PATH。我这儿是set PATHC:\Program Files\GDAL192\bin;%PATH%参数说明C:\Program Files\GDAL192\bin是 gdal192.dll 所在目录要注意是 bin 而不是 lib——我当时一度误把 lib 目录加进去照样报错。这条命令只对当前窗口临时生效想要一劳永逸需要去“系统属性 环境变量”里把 bin 目录追加到系统 PATH追加后必须新开命令窗口或重启 Python 进程因为 PATH 是进程启动时读取的。4. msi 直装路线省事也要栽在 DLL 搜索路径上4.1 选择 msi 时最该留意的是 Python 版本与位数匹配第二条路线简单很多下载官方提供的 msi 安装包双击一路 Next 就装完。我这次依然选的 GDAL 1.9.2 对应版本和源码编译路线保持同一版本避免两个方案的结果互相干扰。下载时眼光要放准msi 是按 Python 版本和系统位数分别打包的必须选 Python 2.7 64 位那一档。选错位数或选错 Python 大版本装完不是启动失败就是 import 直接异常这类问题 msi 安装过程本身不会提示你属于装了才知道错。默认安装路径一般是C:\Program Files\GDAL192装完建议先看一眼目录结构主要确认两点bin 目录下有没有gdal192.dll以及 include、lib、data 是否齐全。bin 下的gdalinfo.exe等命令行工具可以用来独立验证 GDAL 本身是否正常和 Python 绑定的问题分开排查。当时我就是先跑 gdalinfo 验证 core 没问题才敢确定问题只出在 Python 扩展加载环节。4.2 msi 直装后 import gdal 同样报 DLL load failed原因和源码路线一致别以为换 msi 路线就一路顺畅——我装完后第一次import gdal看到的报错和源码路线最后一步一字不差ImportError: DLL load failed: 找不到指定的模块。原因也完全一致msi 安装过程不会自动修改 PATH不会把 bin 目录加进去。gdal.py只是薄薄一层壳真正的_gdal.pyd在加载时动态去找gdal192.dll和它的依赖项找不到就统一报这个错。注意这个“找不到”不是指 Python 代码缺文件而是指 Windows 加载器的 DLL 搜索路径有问题。解决办法还是老一套把 bin 目录追加到环境变量set PATHC:\Program Files\GDAL192\bin;%PATH%关键提醒改完环境变量后一定不要用当前已经开着的 Python 窗口做测试。Python 进程的 PATH 是在启动时继承的你现在这个进程拿到的还是旧值必须完全关掉所有 cmd 和 IDE重新打开一个新窗口再试。这个问题让我白试了五六次以为是环境变量没生效其实只是进程没重启。4.3 用实际输出验证两种方案是否等价两条路线最后都成功后我习惯用一个最小验证脚本确认结果一致python -c from osgeo import gdal; print(gdal.VersionInfo())输出1920表示 GDAL 1.9.2 的 Python 绑定已被成功加载。如果要进一步验证整个读取链路可以再打开一个栅格文件测试Open、RasterXSize、RasterYSize这几个调用。当时我翻看了 core 源码里apps/gdalinfo.cpp大致明白了 GDAL 的读取流程先注册驱动再通过Open拿到数据集句柄最后按波段读取数据。理解这个流程对排查很有用——如果Open返回 None那是数据文件或驱动问题和安装过程无关不要又回头去折腾重装。5. 避坑五个高频踩坑点每个都值得记一次5.1 位数不匹配64 位机器不等于 64 位 Python现象按教程装完 GDALimport 时要么报 DLL load failed要么 Python 进程直接闪退。原因GDAL 的 Python 扩展是 C 扩展必须与解释器位数一致。64 位操作系统能同时运行 32 位和 64 位程序如果电脑上装的是 32 位 Python 2.7常见路径C:\Program Files (x86)\Python27却配了 64 位 GDAL 二进制加载必然失败。解决python -c import struct; print(struct.calcsize(P) * 8)输出 64 说明 Python 是 64 位去下载 64 位 GDAL输出 32 就换 32 位安装包。这个问题用系统位数去推断 Python 位数很容易翻车命令验证最稳。5.2 改完环境变量不生效没有新开终端也没有重启 Python现象在系统属性里把 bin 目录加进 PATH确认路径无误echo 也能看到import 还是同样的报错。原因Windows 的 PATH 在进程启动时读取并缓存已启动的 cmd 和 Python 不会自动感知环境变量变更。解决关闭所有相关窗口和 Python 进程重新打开一个干净的终端再测。顺带一提用set命令加的 PATH 只对当前窗口有效关掉就没了想持久化必须走系统属性。5.3 多个 GDAL 版本在 PATH 里打架现象之前装过 1.11.0后来又换 1.9.2import 成功但VersionInfo()返回的还是旧版本号或者某些功能调用报错。原因DLL 搜索顺序按 PATH 从前到后第一个被命中的 gdal DLL 被加载。多个 bin 目录同时在 PATH 里时命中哪个全看排列顺序表现起来像玄学实际有规律可查。解决where gdal192.dll这条命令会列出所有被搜索路径命中的同名 DLL 及顺序。只保留当前要用的版本 bin 路径把另一个删掉并清理 site-packages 里残留的旧 osgeo 目录。5.4 路径写进 lib 而不是 bin或用户变量与系统变量混用现象明明“加了环境变量”PATH 里也看得到Python 加载还是失败。原因路径本身写错比如把 lib 当成 DLL 所在目录或者变量加在用户变量里而当前终端以系统级权限运行时两边环境变量并不完全互通。解决用where gdal192.dll确认最终生效位置统一把 bin 路径写进系统变量让所有进程一致生效。5.5 试图用 mingw 绕过 Vcvarsall.bat编译能过导入崩溃现象照网上方案执行python setup.py build --compilermingw32编译过程报一堆错勉强编出的 pyd 在 import 时直接崩溃。原因Python 2.7 官方二进制基于 MSVC 构建C 扩展与解释器之间通过 MSVC 的 CRT 数据结构传递对象。mingw 的运行时与 MSVC 的 ABI 有差异代码虽能编出来运行期却拿不到可靠保证。我实验时就是这条路线失败的。解决老老实实用 MSVC 工具链set VS90COMNTOOLS%VS100COMNTOOLS%后重编一次通过。6. 快速定位三步确认 GDAL Python 环境是否真正可用6.1 先定架构再查 DLL最后看加载结果以后再遇到 DLL load failed我一般按三步走五分钟内能分清是版本问题、环境变量问题还是数据问题。第一步确认 Python 与扩展的位数是否一致python -c import struct; print(struct.calcsize(P) * 8)第二步确认目标 DLL 在系统里存在且位置唯一where gdal192.dll第三步最小化加载测试python -c from osgeo import gdal; print(gdal.VersionInfo(), gdal.__file__)如果第三步失败把报错指向的 pyd 用依赖查看工具打开看缺失 DLL 的名称再去 PATH 里补对应目录。DLL load failed 的根因九成以上在 pyd 的动态依赖而不是 Python 代码抓住这个认知比盲试任何安装方案都省时间。6.2 一张检查清单收住常见情况检查项命令通过标准Python 位数python -c import struct; print(struct.calcsize(P) * 8)输出 64与 GDAL 相符DLL 位置where gdal192.dll返回唯一且正确的 bin 路径扩展加载python -c from osgeo import gdal; print(gdal.VersionInfo())输出 1920 或其他版本号环境变量生效echo %PATH%新开终端后能看到 bin 目录从那以后我每次在新的 Windows 机器上装 GDAL都强制走一遍“查位数 → where 查 DLL → 加 PATH → 重启终端 → import 验证”再也没有因为 DLL load failed 浪费超过十分钟。这个流程同样适用于其他带 C 扩展的地理库比如 shapely、pyproj它们的报错形态和 root cause 大同小异。希望这篇复盘能帮你少走一点弯路。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
