GeoPandas 导出 KMZ 的可行写法

Python
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

GeoPandas 本身没有单独的 to_kmz 方法,但导出 KMZ 完全可行:若底层 GDAL 已启用 LIBKML 驱动,可直接用 GeoDataFrame.to_file 写出 .kmz;更稳妥、跨环境通用的做法是先写出 .kml,再用 zipfile 打成以 doc.kml 为主文件的压缩包。导出前务必把坐标系转到 EPSG:4326,并先用 list_drivers 确认驱动可用。截至 2026 年 11 月,推荐使用 GeoPandas 1.2.x,配合 conda-forge 安装以获得更完整的 LIBKML 支持。

KMZ 本质是包含 doc.kml 的 ZIP 包,可被 Google Earth 等直接打开

导出前先确认驱动和环境

KMZ 能否直接写出,取决于当前环境里的 OGR/GDAL 驱动,而不是 GeoPandas 本身。GeoPandas 1.2.0(2026 年 9 月 28 日发布)要求 Python ≥3.11、pandas ≥2.2、numpy ≥2.0、shapely ≥2.1、pyproj ≥3.7、pyogrio ≥0.8;默认引擎优先 pyogrio,未安装时回退到 fiona。pip 安装的 pyogrio wheels 在较新版本(约 0.13 起)的部分平台已带上 libkml,但 conda-forge 渠道通常更完整,同时提供 KML 与 LIBKML。

动手前先检查驱动:导入 pyogrio 后调用 list_drivers,看是否出现 KML 或 LIBKML,且标记为可写;若用 fiona,还需手动把 supported_drivers 里对应项设为可读写。若驱动缺失,优先改用 conda install -c conda-forge geopandas,而不是硬改 pip 环境。版本发布记录可在 GeoPandas GitHub tags 页面 核对。

项目 要求或说明
推荐版本 GeoPandas 1.2.x(截至 2026 年 11 月)
Python ≥3.11
默认引擎 pyogrio(已安装时);否则 fiona
KMZ 首选驱动 LIBKML(支持 .kmz 创建与多层)
安装建议 conda-forge 更易获得完整 GDAL 驱动

方法一:用 LIBKML 直接写出 KMZ

当 list_drivers 显示 LIBKML 可写时,这是最短路径。LIBKML 基于 libkml,可把 .kmz 当作数据源创建,并支持样式、Schema、多层等,细节见 GDAL LIBKML 驱动文档。

  1. 确认 GeoDataFrame 的 CRS 为 EPSG:4326;若不是,先 to_crs(4326)。
  2. 清理不支持的复杂列(如 list、tuple、嵌套对象),必要时转成字符串或拆列。
  3. 调用 to_file,文件名以 .kmz 结尾,driver 设为 “LIBKML”;需要时可指定 engine=”pyogrio” 或 “fiona”。
  4. 用 Google Earth、QGIS 或同环境 read_file 回读,检查几何与属性是否完整。

注意:部分环境下 KML 驱动对 KMZ 读写支持有限,属性可能出现 ExtendedData 错位;遇到这种情况优先改用 LIBKML,或切换到 fiona 引擎。

方法二:先写 KML 再打包成 KMZ(更通用)

没有 LIBKML、或需要把多个 GeoDataFrame 放进带 Folder 结构的单个 KMZ 时,用“先 KML 后 ZIP”更可靠。KMZ 就是 ZIP,主文件通常叫 doc.kml。

  1. 把所有要导出的图层统一到 EPSG:4326,并处理好属性类型。
  2. 用 to_file 写出 .kml(driver=”KML” 或 “LIBKML”)。若 Fiona 报 unsupported driver,先启用 KML/LIBKML 驱动再写。
  3. 用 Python 标准库 zipfile 新建 .kmz:把刚才的 kml 以名称 “doc.kml” 写入压缩包;若有图标等附属文件,一并放入。
  4. 需要文件夹结构时,不要指望 to_file 一次生成复杂嵌套,可先拼好带 Folder 的 KML 文本再打包,或分图层写多个 kml 后按约定路径塞进同一个 ZIP。
  5. 验收:改后缀为 .zip 解压,确认存在 doc.kml;再在地球软件中打开验证。

这种方式不依赖特定 wheel 是否编译了 libkml,跨 pip/conda、跨平台更稳。大文件写入时可尝试 use_arrow=True(需 pyarrow)提升速度;若整体读写偏慢,可参考本站 GeoPandas 读取慢与空间索引做法 先优化源数据。

GDAL 官网 LIBKML 驱动说明页,可见其对 KMZ 创建与能力的描述
GDAL 官网 LIBKML 驱动说明页,可见其对 KMZ 创建与能力的描述(截图来源:gdal.org)

CRS、属性、中文和引擎选择要注意什么

KML/KMZ 标准基于 WGS84,非 4326 的几何写出后位置会错,务必先投影转换。属性会进 ExtendedData;列名尽量简洁,避免特殊字符。中文属性或文件路径若出现乱码,写入侧同样要管好编码——导出 GeoJSON 时的中文处理思路可迁移过来,详见 Geopandas 导出 GeoJSON 中文乱码解决;读取侧编码参数设置可对照 GeoPandas 读取乱码与编码参数说明。

  • 引擎:优先 pyogrio;属性错位或 KMZ 读不进时改试 engine=”fiona”。
  • 几何:多几何列需先处理;Z 值有时会被 LIBKML 自动带上,验收时留意。
  • 驱动启用:Fiona 默认不一定暴露 KML/LIBKML,写前显式打开读写支持。
  • 多层/文件夹:直接 to_file 能力有限,复杂结构用手动 KML + ZIP。

常见问题

报错 unsupported driver: ‘KML’ 或 ‘LIBKML’ 怎么办?

先 list_drivers 确认当前环境有没有该驱动。没有就改用 conda-forge 重装 geopandas/pyogrio;若用 Fiona,手动把 supported_drivers 对应项设为可读写后再 to_file。仍失败则改用“先 KML 再 ZIP”的通用写法。

写出的 KMZ 属性列错位或 ExtendedData 对不上?

这是部分 KML 驱动的老问题。改用 driver=”LIBKML”,或显式指定 engine=”fiona” 再写;同时检查列类型是否含复杂对象,提前转成简单类型。

pyogrio 读不了刚导出的 KMZ?

普通 KML 驱动对 KMZ(ZIP)支持有限。读取时指定 driver=”LIBKML”,或改用 engine=”fiona”;也可尝试以 /vsizip/ 前缀打开包内 doc.kml。以本机实际 list_drivers 结果为准。

多个 GeoDataFrame 如何放进同一个带文件夹的 KMZ?

GeoPandas/Fiona 不能直接生成复杂 Folder 嵌套。分别写出或拼好带 Folder 节点的 KML,再统一打成以 doc.kml 为主文件的 ZIP;需要样式或 NetworkLink 时,LIBKML 能力更强,但仍建议最终用 ZIP 封装验收。

总结:能直接用 LIBKML 就写 .kmz,否则一律走“KML + 打成 doc.kml 的 ZIP”。动手前检查驱动、统一 EPSG:4326、验收几何与属性。建议优先 conda-forge 环境,并把导出结果在 Google Earth 或 QGIS 里打开确认一遍。