简介针对 Windows 7 64 位平台下 Python 2.7 安装 GDAL 的教程文档面向需要使用 GDAL 处理地理空间数据的开发者特别是初次接触时经常遇到编译与依赖问题的用户。文档详细梳理了安装前的环境准备包括 Visual Studio 2010、GEOS 3.3.8 与 Python 2.7并对比介绍了源码编译与官方 MSI 安装两种方案清晰标注了操作命令与目录切换等关键细节。文中还给出了 swig.exe 未安装时环境变量的配置方法以及 DLL load failed 时 bin 目录的添加路径方便读者对照操作。资源仅含 1 个 docx 文档大小约 95KB内容涵盖环境配置、两种安装路径、安装结果验证以及常见错误排错既有操作步骤又有附录错误表便于逐项排查。整个安装流程经过真实环境验证排错思路完整按文档操作可少走弯路。已有 628 人浏览学习对计划在旧版 Windows 与 Python 环境中部署 GDAL 的用户具有直接参考价值可有效节省自行摸索的时间。1. 老机器上装 GDAL源码编译与 MSI 安装两条路我都走通了在 Win7 64 位这台还在服役的老机器上给 Python 2.7 装 GDAL是我最近做过最折腾的事不是缺 swig 就是找不到 Vcvarsall.bat好不容易装上import gdal 又开始报 DLL 加载失败。我把源码编译和官方 MSI 两条路线都完整走通以后最大的体会是别盲目追新GDAL 1.9.2 在 2013 年的环境里远比 1.11.0 稳网上资料多到能让你迷路但踩坑记录也更完整。这份资源解决的是两件事一是把 GDAL 的 C 核心装好二是让 Python 2.7 能 import gdal并顺利读取栅格数据。如果你跟我一样在 Win7 64 位下用 VS2010 开发或者想快速用上测绘、遥感里的 GDAL 工具这篇笔记里的每一步命令、每一处环境变量都能让你少走半天弯路。适合那种“机器不能换、Python 版本不能升、但功能必须跑起来”的场景。2. 安装前的预备工作版本搭配、环境变量和 x64 命令提示符2.1 版本搭配GDAL 1.9.2 不是越老越好是刚刚好在开装之前先把这堆版本的依赖关系捋清楚。GDAL 本身是一个 C 库Python 要调用它不是直接通过 ctypes而是通过 SWIG 生成的包装层。这个包装层在编译时会调用 Python.h 和 Python 的导入库同时要链接到 gdal 的核心 DLL。也就是说你现在用的 Python 是哪一版、VS 是哪一版、GDAL 源码是哪个版本三者必须能对上号。我一开始图新鲜选了 GDAL 1.11.0结果在编译 swig 包装时遇到一个关于gdal_version.h宏定义错误满世界找资料只找到一篇博客而且那是针对 1.9.2 的。换回 1.9.2 后同样的操作一次通过。这个版本的“资料多”本身就是最大的优势——遇到问题你能快速定位到你当前版本而不是在一个泛泛的“新版”下面猜答案。GEOS 3.3.8 是个空间几何运算库GDAL 的 OGR 模块在编译时可以链接它。如果只是做栅格读写的安装不装 GEOS 也能跑但一旦你后续要处理矢量相交、缓冲区这类操作缺少 GEOS 的 GDAL 会在运行时直接报“GEOS support not enabled”。所以我在安装时把 GEOS 也一并准备好。VS2010 则是这一切的编译基石它提供 nmake 程序维护工具、C 编译器和 vcvarsall.bat 批处理。装了 VS2010 但不装 VC 组件后面编译会报“找不到 cl.exe”这一点很容易被忽略。另一个需要提前决定的是走源码编译还是 MSI。源码编译需要 VS2010 和 swig适合想了解 GDAL 架构的人MSI 装起来快但没法看到中间产物。我这次是两条都走了所以后续章节会分别讲。提前决定路线能帮你明确安装顺序避免装到一半才想起来缺工具。我把这组版本整理成一张表你对着匹配能省掉很多后续的“找不到头文件”问题组件推荐版本作用注意事项操作系统Win7 64 位目标平台命令提示符要用 x64 兼容版否则环境变量不完整Visual Studio2010编译工具链必须包含 VC 组件提供 nmake 和 cl.exeGDAL1.9.2核心地理数据抽象库可选 1.11.0但 1.9.2 踩坑资料更多GEOS3.3.8空间几何运算库编译 GDAL 时可选依赖建议安装Python2.7脚本环境注意是 32 位还是 64 位需与 GDAL DLL 位数一致SWIG2.10.0生成 Python 包装代码源码编译路线必需MSI 路线不需要这里要特别说一句 Python 位数的问题。Win7 64 位系统可以装 32 位或 64 位的 Python 2.7而我最终用的是 32 位版本因为 GDAL 1.9.2 在 Win7 上常见的预编译 DLL 是 32 位。如果你装了 64 位 Python而手头只有 32 位 gdal192.dllimport 时照样报“找不到指定的模块”。所以选版本时把 Python 位数和 GDAL 的位数保持一致比纠结 GDAL 大版本更关键。2.2 用对命令提示符为什么普通 cmd 跑不了 nmake普通 cmd 窗口里没有 nmake、cl.exe 这些编译工具的环境变量。nmake 是 VS 自带的程序维护工具它从 makefile.vc 里读取编译规则而 makefile.vc 里写死了要调用 cl.exe 以及一堆 include/lib 路径。这些路径只有在执行过 vcvarsall.bat 之后才会被设置到当前会话中。VS2010 的“Visual Studio x64 兼容工具命令提示符”就是预先调好 vcvarsall.bat 并让它以 x64 目标架构配置环境变量的一个快捷方式。我试过在普通 cmd 里手动 cd 到 VC 目录运行vcvarsall.bat x64偶尔能生效但一旦目录带空格或路径有特殊字符就会出错而快捷方式不存在这个问题。正确的打开方式是点“开始 → 所有程序 → Microsoft Visual Studio 2010 → Visual Studio Tools → Visual Studio x64 兼容工具命令提示符”然后右键选择“以管理员身份运行”。为什么要管理员权限因为后续 nmake 会把生成的文件写到 swig 目录下有些目录权限不够会拒绝写而且 Python 的 setup.py install 要往 C:\Program Files (x86)\Python27\Lib\site-packages 里写 .py 和 .pyd 文件非管理员会报权限错误。打开后先把目录切换到 GDAL 源码的 swig 子目录假设解压在 C:\OGC\GDAL192\gdal-1.9.2cd C:\OGC\GDAL192\gdal-1.9.2\swig然后验证环境是否就绪echo %VCINSTALLDIR%如果输出了类似C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC的内容说明编译环境已经有效若为空你需要重新用上面的快捷方式打开别继续硬跑。除了快捷方式你还可以在普通 cmd 里执行call C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat x64但路径中的空格容易被转义所以我不推荐。而且手动调用无法获得 VS 完整的内部变量比如_VSPROMPT。用自带快捷方式最稳。2.3 配置 Path提前给 swig 和 gdal192.dll 找好家无论走源码编译还是 MSI 安装最后系统都得能找到 swig.exe 和 gdal192.dll。Swig 是源码编译路线的外部工具下载 swigwin-2.10.0 解压后把 swig.exe 所在目录比如 C:\swigwin-2.10.0加入系统环境变量 Path。GDAL 的 bin 目录在源码编译时是C:\OGC\GDAL192\gdal-1.9.2\bin在 MSI 安装时是C:\Program Files\GDAL192或你自己指定的安装路径下的 bin。操作步骤是右击“计算机 → 属性 → 高级系统设置 → 环境变量”在“系统变量”中找到 Path点“编辑”把这两个目录追加进去用分号与原有项分隔。之所以要提前配是因为 Python 在 import gdal 时通过_gdal.pyd加载 gdal192.dllWindows 的 DLL 搜索顺序包括应用程序目录、系统目录、当前目录以及 Path 中列出的目录。如果不加 bin就一定会出现“DLL load failed: 找不到指定的模块”。这个错误我在源码编译和 MSI 两条路线里都遇到了属于共性问题不如一开始就堵死。配置完记得把命令提示符窗口关闭重开让新的 Path 在该会话中生效。你可以在新窗口里输入where swig检查 swig 是否被识别如果打印出完整路径说明 Path 配置成功。环境变量修改后不仅命令行窗口要重开如果 Python 是直接从 IDLE 启动的IDLE 也要重启否则在 IDLE 里运行 import gdal 仍然会报同样的 DLL 错误。这个细节我差点漏掉。另外如果你还装了 Python 的第三方 IDE它们同样会缓存环境变量最好全部重启一遍。3. 源码编译路线nmake 生成绑定、setup.py 安装与三处必踩的坑3.1 生成 Python 包装nmake /f makefile.vc python 和 swig 的依赖源码编译路线的第一步是在 swig 目录下执行 nmake让 makefile.vc 帮你生成 Python 包装代码。在 x64 兼容工具命令提示符中先确保当前目录是C:\OGC\GDAL192\gdal-1.9.2\swig然后输入nmake /f makefile.vc python这条命令的行为是先更新 setup.ini 写入 GDAL 的安装路径然后 cd 到 python 子目录调用 swig.exe 去解析 gdal 的 .i 接口定义文件生成gdal_wrap.c和osgeo/gdal.py等一整套包装产物。/f参数指定 makefile 文件名因为默认文件名是 makefile而 GDAL 把 Windows 专用的规则放在 makefile.vc 里所以必须显式指定。我第一次跑这条命令时卡在了swig.exe 不是内部或外部命令。这就是因为机器上根本没装 SWIG。SWIG 是一个独立的代码生成工具GDAL 的源码里只有接口文件并不附带 swig.exe。解决办法是下载 swigwin-2.10.0这个版本在 Python 2.7 时代是稳定选择。解压后把 swig.exe 所在的整个目录加进 Path具体方法见 2.3。配置完成后重新打开命令提示符先where swig确认能找到再重新执行 nmake 命令。这次 nmake 会在 python 子目录下生成一堆 .c 和 .py 文件如果没有任何 fatal error说明包装代码生成成功。我建议你在执行后查看一下swig/python/osgeo/目录正常情况下里面会有_gdal.pyd的骨架文件注意此时还没编译成真正的扩展还有gdal.py、ogr.py等纯 Python 包装层文件。nmake 只负责从接口文件生成 C 源码真正的 .pyd 要靠接下来的 setup.py 编译。3.2 编译扩展模块setup.py build 与 Vcvarsall.bat 的经典错误包装代码生成完毕就要在swig/python目录下编译 Python 扩展。先进入该目录cd C:\OGC\GDAL192\gdal-1.9.2\swig\python然后运行python setup.py build python setup.py installsetup.py build的作用是调用 distutils把上一步生成的 .c 文件编译成_gdal.pyd然后复制到build\lib.win32-2.7这样一个临时目录。setup.py install则把生成的模块和一堆 .py 文件安装到 Python 的 site-packages 目录里也就是C:\Program Files (x86)\Python27\Lib\site-packages\osgeo。这里几乎所有人都会遇到unable to find Vcvarsall.bat报错。原因在于 Python 2.7 的 distutils 默认去寻找 VS2008VC9的编译环境因为 CPython 2.7 官方是用 VS2008 编译的。而我机器上装的是 VS2010VC10distutils 在注册表里找不到 VS2008 对应的 Vcvarsall.bat就直接罢工。网上有好几种解法有人用 mingw我试了因为 GDAL 的 C 代码里用了很多微软特有的约定mingw 根本编不过果断放弃。一个轻量级的简单方案是设置环境变量把 VS2010 的路径指给 VS90COMNTOOLSset VS90COMNTOOLS%VS100COMNTOOLS%VS100COMNTOOLS是 VS2010 安装时自动设置的系统环境变量指向其工具目录比如C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\Tools\。distutils 在找不到 VS2008 时会检查VS90COMNTOOLS我们用这条命令把 VS2010 的工具路径“伪装”成 VS2008 的它就能找到 Vcvarsall.bat 了。这个 set 命令只对当前命令行窗口有效所以必须和随后的 build/install 命令在同一个窗口里执行。执行 setup.py build 时控制台会刷出大量的编译信息其中夹着一些 warning比如宏重定义、符号截断这些通常不影响最终结果。关键是看最后有没有出现error C...或fatal error LNK...。我这次编译打印了几十条 warning吓得我以为失败后来发现 install 正常import 也能用才知道那些 warning 是 GDAL 源码里早就存在的跟我们的环境无关。所以看到 warning 别慌只要没有硬错误就可以继续。另外如果 setup.py build 过程中报找不到 Python.h说明 Python 的 include 目录没设置到位。虽然 distutils 会自行定位但有时 GDAL 的 makefile.vc 会在编译选项中覆盖 include 路径此时需要手动指定环境变量PYTHON_INCLUDE_DIR和PYTHON_LIBRARY。不过 1.9.2 的默认配置里一般不会出这个问题我在多次尝试中只在 1.11.0 上遇到过。3.3 install 后 import 报错DLL 搜索路径与 bin 目录的真相setup.py install 成功后在命令提示符里测试导入python -c import gdal如果看到ImportError: DLL load failed: 找不到指定的模块这并不代表编译失败而是 Python 在导入osgeo._gdal时找不到 gdal192.dll。_gdal.pyd是一个动态链接库它内部链接了gdal192.dll。Windows 在加载_gdal.pyd时会按 DLL 搜索顺序去找gdal192.dll而默认顺序里并不包含 GDAL 编译产物的 bin 目录。解决方法是把 bin 目录加进 Path。源码编译产物的 bin 目录是C:\OGC\GDAL192\gdal-1.9.2\bin里面有 gdal192.dll、gdalinfo.exe 等一系列可执行文件和动态库。把它加到系统 Path 后重新打开命令行窗口再测试python -c import gdal这次会顺利通过。如果你用的是 IDLE 或 Spyder配置完 Path 后必须重启这些编辑器因为它们会缓存环境变量。我一度在 IDLE 里反复 import 失败却在 cmd 里成功就是这个缓存原因。4. MSI 快速路线下载匹配版本、直接安装、补一条 Path4.1 下载官方 MSI版本匹配 Python 2.7 和 Windows 位数的关键如果你不想碰编译官方提供的 MSI 安装包就是最省事的路。GDAL 官方有 Windows 预编译的 MSI其中包含了 gdal192.dll、命令行工具和 Python 绑定。下载时要注意两个匹配一是 MSI 的版本要对应 GDAL 1.9.2或你想要的 1.11.0二是 MSI 的位数要能与你的 Python 版本匹配。因为 Python 2.7 在 Win7 64 位下通常装的是 32 位版本所以你要找标记为win32的 MSI而不是amd64。如果装错安装过程可能正常但 import gdal 时一样会报 DLL 加载失败因为扩展模块的位数和 Python 解释器的位数不一致。双击 MSI 后会进入标准的安装向导。我一般选择默认安装路径也就是C:\Program Files\GDAL192这个路径后面还要用到。安装向导里如果出现“Python bindings”或“osgeo”之类的选项一定要确保它是启用的。有些精简版 MSI 会默认取消 Python 绑定那样装完只有核心库Python 里并没有 osgeo 模块。如果你不确定可以在安装后打开C:\Program Files\GDAL192\python目录里面至少要有 osgeo 文件夹才算正常。4.2 安装顺序与权限先装 Python 2.7再装 MSI用管理员安装MSI 安装有一个容易被忽略的依赖顺序必须先把 Python 2.7 装好再执行 GDAL 的 MSI。因为 MSI 里的 Python 绑定是通过扫描注册表里的 Python 安装信息来定位 site-packages 的如果 Python 还没装绑定组件就会静默跳过。我见过有人先装 GDAL 后装 Python结果 GDAL 提示安装成功可 Python 里什么都没有只能重装。另外MSI 安装到C:\Program Files需要管理员权限如果你的系统开启了 UAC双击安装时一定要右键“以管理员身份运行”否则可能在最后写入注册表时失败。安装完成后我会第一时间检查C:\Program Files (x86)\Python27\Lib\site-packages\osgeo这个目录是否存在。如果存在且里面有gdal.py、_gdal.pyd说明绑定已经装好。如果只有gdal.py而没有_gdal.pyd说明 MSI 没识别到 Python 的扩展模块多半是 Python 安装的是 64 位而你下载了 32 位 MSI或者反过来。4.3 安装后检查Path 修正与 DLL 搜索顺序MSI 安装完成后打开命令行窗口输入python -c from osgeo import gdal; print(gdal.VersionInfo())如果打印出一串版本号比如1910说明安装成功。如果出现ImportError: DLL load failed: 找不到指定的模块多半还是 Path 里没有 gdal192.dll 的目录。MSI 默认把 gdal192.dll 放在C:\Program Files\GDAL192你需要把这个目录加到系统 Path。另外MSI 安装的 Python 模块在C:\Program Files (x86)\Python27\Lib\site-packages\osgeo如果这里没有生成可能 MSI 在安装时没能判断出 Python 安装位置。这时可以手动把C:\Program Files\GDAL192\python\osgeo复制到 site-packages 下或者重新安装 MSI 并确保 Python 2.7 已预先安装。即使 MSI 安装时勾选了“Add GDAL to PATH”我也建议用where gdal192.dll再确认一次。因为有些版本的 MSI 只把gdalinfo.exe所在的 bin 目录加入 Path却漏掉了gdal192.dll本身的目录两者虽然通常在同一目录但偶尔有例外。执行where gdal192.dll如果输出C:\Program Files\GDAL192\gdal192.dll说明系统能找到如果提示找不到就手动补路径。4.4 源码编译 vs MSI我为什么两条都留下来了我在这次安装中把两条路线都跑了一遍不是为了凑字数而是它们在后续维护中有不同的价值。源码编译虽然前置条件多但你能拿到全套中间文件比如 gdalinfo.exe 可以直接在命令行用而且当你需要改动 GDAL 的源码做二次开发时一切都在手边。MSI 安装快适合只想要一个能用的 Python 包、不愿意折腾编译的人。我把两者的差异列成一张表你根据自己的能力边界做选择对比项源码编译MSI 安装编译耗时5-10 分钟2 分钟环境要求VS2010、SWIG、GEOS只需要 Python 2.7踩坑数量多但资料全少但资料零散可控性可改源码、可调编译参数黑盒只能装固定版本适合人群C 基础好、要做二次开发用 Python 做批处理、快速上手就我个人的习惯遇到新机器我会先用 MSI 装一个能用的环境确认项目能跑如果后面要深入 GDAL 源码或者定制插件再回头用源码编译把中间产物保留下来。两条路线共享一份环境变量配置所以第一遍把 Path 弄好第二遍会顺很多。另外MSI 安装后osgeo目录里的_gdal.pyd和gdal192.dll位置可能不同有时候 DLL 在 Program Files\GDAL192而 pyd 在 site-packages\osgeo。Python 导入 pyd 后pyd 会去找 DLL如果找不到就会报错。所以即便 MSI 安装时添加了 Path也最好用where gdal192.dll检查一下。5. 安装避坑指南四个报错现场的原因与修复步骤5.1 swig.exe 不是内部或外部命令现象执行nmake /f makefile.vc python时控制台提示“swig.exe 不是内部或外部命令也不是可运行的程序或批处理文件”nmake 立即停止。原因系统没有安装 SWIG或者安装后没把 swig.exe 所在目录加入环境变量 Path。GDAL 源码只提供接口文件swig 是独立的生成器需要额外下载。解决下载 swigwin-2.10.0解压到一个无空格路径如 C:\swigwin-2.10.0。将C:\swigwin-2.10.0添加到系统 Path。重新打开命令提示符先where swig确认识别成功再重跑 nmake。5.2 unable to find Vcvarsall.bat现象执行python setup.py build时distutils 报 “error: Unable to find vcvarsall.bat”编译直接终止。原因Python 2.7 的 distutils 默认按照 VS2008 编译的 CPython 来找编译器。机器上装的是 VS2010注册表里没有 VS2008 的 Vcvarsall.bat 路径导致 distutils 放弃查找。解决用命令set VS90COMNTOOLS%VS100COMNTOOLS%把 VS2010 的工具路径伪装成 VS2008 的。设置后在同一窗口中重新执行python setup.py build和python setup.py install。注意这个 set 只对当前窗口有效所以每一步都要在同一个窗口里连贯执行。5.3 ImportError: DLL load failed: 找不到指定的模块现象安装完成后import gdal或from osgeo import gdal报“ImportError: DLL load failed: 找不到指定的模块”。这个问题在源码编译和 MSI 方案中都出现过。原因Python 导入_gdal.pyd时系统搜索不到它依赖的gdal192.dll。这只说明 DLL 搜索路径不完整与 Python 代码本身无关。解决把 GDAL 的 bin 目录加入系统 Path。源码编译时是C:\OGC\GDAL192\gdal-1.9.2\binMSI 安装时是C:\Program Files\GDAL192。加完 Path 后找出你自己使用的环境如果是命令行就重开窗口如果是 IDLE 就重启 IDLE再试导入。5.4 编译期间 error C1083: 找不到 gdal_version.h 或 gdal.h现象setup.py build 时输出类似fatal error C1083: 无法打开包括文件: gdal.h: No such file or directory编译停止。原因GDAL 的源码中Python 绑定的编译需要依赖核心库的头文件。如果 makefile.vc 里的 include 路径没有指向 gdal 源码的gcore和port目录就会找不到头文件。常见于路径中含空格、或者解压目录不是预期路径的情况。解决确认 GDAL 源码解压路径中没有空格推荐直接放 C:\OGC\GDAL192\。然后检查 swig\python 目录下的 setup.py 是否有写死相对路径的选项必要时在编译前设置环境变量GDAL_INCLUDEC:\OGC\GDAL192\gdal-1.9.2\gcore。这个坑在默认官方源码包中较少出现但我在精简版源码包里踩到过。6. 装完怎么验证先跑 gdalinfo再写三行 Python 读栅格6.1 用 gdalinfo 命令行工具验证核心库装完 GDAL 后第一件事不是急着写 Python而是先跑命令行工具。打开任意命令提示符现在普通 cmd 也可以了因为环境变量已经配好输入gdalinfo --version如果输出类似GDAL 1.9.2, released 2012/10/08的版本信息说明核心库和命令行工具都能工作。再拿一个真实的 TIFF 文件试试gdalinfo C:\your\path\test.tif在输出里能看到影像尺寸、波段数、投影坐标、地理范围等元数据。如果命令找不到 gdalinfo说明 GDAL 的 bin 目录不在 Path 中回到 2.3 补一遍。6.2 用 Python 读取栅格元数据和第一个波段命令行工具正常后再验证 Python 绑定。写一个十几行的脚本from osgeo import gdal import sys # 打开栅格文件 ds gdal.Open(rC:\your\path\test.tif) if ds is None: sys.exit(无法打开文件检查路径和GDAL安装) # 读取元数据 print(尺寸: {}x{}.format(ds.RasterXSize, ds.RasterYSize)) print(波段数: {}.format(ds.RasterCount)) # 读取第一个波段的数据 band1 ds.GetRasterBand(1) arr band1.ReadAsArray() print(第一个波段数组形状:, arr.shape) print(数组最大值:, arr.max())gdal.Open返回一个 Dataset 对象RasterXSize和RasterYSize分别代表列数和行数。GetRasterBand(1)取得第一个波段ReadAsArray()把栅格数据读成 NumPy 二维数组方便做统计和裁剪。如果这一步有输出说明 Python 已经成功调起底层 GDAL DLL。6.3 一个常用技巧用from osgeo import gdal不要写import gdal很多旧教程会让你直接import gdal但在 GDAL 1.9.2 的 Python 绑定里这个写法会触发 deprecation_warn。更规范的是from osgeo import gdal它直接进入真正的绑定模块不经过兼容层。我一开始用import gdal也跑通了但总会在控制台看到一个 FutureWarning后来改成from osgeo import gdal后干净很多。这也算是一个容易被忽略的小细节。从那以后我每次在新机器上装 GDAL都会强制走一遍 gdalinfo --version 和这个十几行的读栅格脚本确认环境和数据链路都通了才敢继续写业务代码。希望这个习惯也帮到你。本文还有配套的精品资源点击获取