• GIS
• 遥感
• 数据工程

本指南面向准备参加 GDAL 新命令行界面（CLI）工作坊的开发者，系统梳理 GDAL 3.13.1 在 Linux、macOS、Windows 三大平台上的安装路径，以及工作坊专用示例数据集的获取方法。读完本文，你将能够独立完成从零搭建 GDAL 命令行工作环境、验证版本与数据完整性，并配置面向 Bash 的gdal命令自动补全，为后续栅格/矢量处理练习（参见 工作坊章节索引）做好全部准备。

版本基线：GDAL 3.13.1 "Iowa City"

本工作坊要求使用GDAL 3.13.1（2026 年 6 月发布），安装完成后可通过以下命令确认版本：

gdal --version

预期输出：

GDAL 3.13.1 "Iowa City", released 2026/06/01

需要说明的是，本文撰写所依据的工作坊安装文档以 3.13.1 稳定版为基线；而当前仓库主线的 VERSION 文件已标记为 3.14.0，若你使用文末介绍的gdal-master开发渠道，版本号与功能均以实际构建为准，请勿混用稳定版环境变量。

为什么推荐 Conda：面向原生依赖的包管理

工作坊文档给出的推荐安装方式是使用GDAL Conda 构建。Conda 是一套可在主流桌面操作系统（Linux、Windows、macOS）上运行的系统级包管理工具，主要服务于 Python 生态，但其核心优势在于能正确处理 GDAL 这类带原生依赖（native dependencies）的软件——从编译期依赖库到可选的栅格/矢量驱动插件，都由 Conda 统一解决二进制兼容问题，免去手工编译。

工作坊所面向的gdal新 CLI 自 GDAL 3.11 引入，是对传统gdal_translate、ogr2ogr等工具的补充，提供更统一、可预测、更友好的交互体验（详见工作坊简介与仓库 README）。新 CLI 采用 git 风格的分层命令结构（gdal raster info、gdal vector convert、gdal mdim info、gdal pipeline、gdal vsi list等），详见新 CLI 通用原则。因此，一套正确安装的 GDAL 环境是后续所有练习的共同前提。

各平台安装路径概览：

Linux 平台安装

Linux 用户有两种选择：一是直接使用包含二进制与工作坊示例数据的 Docker 镜像；二是在宿主机用 Conda 安装 GDAL 与配套包并自行下载测试数据。前者在已安装 Docker/Podman 的情况下更省事；后者手工步骤更多，但与系统集成更自然。

方式一：Docker 镜像（开箱即用）

前提：已安装 Docker 或 Podman。拉取工作坊专用镜像：

docker pull ghcr.io/gdal/gdal-cli-workshop

允许容器内的 X 客户端连接宿主机的 X server（图形界面转发，供 QGIS 使用）：

xhost +local:root

输出：

non-network local connections being added to access control list

启动容器：

mkdir -p $HOME/gdal-cli-workshop docker run -it --name gdal-cli-workshop \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v $HOME/gdal-cli-workshop:/data/gdal_cli_workshop_data-master/host \ ghcr.io/gdal/gdal-cli-workshop

各参数作用：

容器内验证 GDAL：

(base) root@XXXXXXXXXXXX:/# gdal --version

GDAL 3.13.1 "Iowa City", released 2026/06/01

示例数据已预置在镜像内，位于/data/gdal_cli_workshop_data-master/：

(base) root@XXXXXXXXXXXX:/# cd /data/gdal_cli_workshop_data-master/ (base) root@XXXXXXXXXXXX:/# ls -al

total 91296 drwxr-xr-x 5 root root 4096 May 22 01:37 . drwxr-xr-x 3 root root 4096 May 22 04:12 .. -rw-r--r-- 1 root root 18925846 May 22 01:37 20260519_00_tmp2m.nc -rw-r--r-- 1 root root 18925846 May 22 01:37 20260519_06_tmp2m.nc -rw-r--r-- 1 root root 1756 May 22 01:37 README.md drwxr-xr-x 6 root root 4096 May 22 01:37 S2B_MSIL2A_20260423T094029_N0512_R036_T34TDR_20260423T115714.SAFE drwxr-xr-x 6 root root 4096 May 22 01:37 S2B_MSIL2A_20260423T094029_N0512_R036_T34TER_20260423T115714.SAFE drwxr-xr-x 6 root root 4096 May 22 01:37 S2B_MSIL2A_20260423T094029_N0512_R036_T34TES_20260423T115714.SAFE -rw-r--r-- 1 root root 35131910 May 22 01:37 dem.tif -rw-r--r-- 1 root root 14909524 May 22 01:37 ne_10m_admin_1_states_provinces.zip -rw-r--r-- 1 root root 5493 May 22 01:37 osm_conf_amenity.ini -rw-r--r-- 1 root root 5528366 May 22 01:37 timisoara.osm.pbf drwxrwxr-x 2 1000 1000 4096 May 22 05:06 host

最后验证 QGIS 也能正常启动：

(base) root@XXXXXXXXXXXX:/# qgis

QGIS 窗口成功出现后，Docker 路线的安装即告完成，可直接跳过本页其余内容。

方式二：Conda 安装（与宿主机深度集成）

1. 安装 Miniforge3

如果还没有任何 Conda 安装，先下载 Miniforge3 安装脚本（Linux x86_64 对应文件名为Miniforge3-Linux-x86_64.sh，可从 conda-forge 官方 Miniforge 发布渠道获取）：

curl -LO https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh

静默安装：

sh Miniforge3-Linux-x86_64.sh -b

输出节选：

PREFIX=/home/even/miniforge3 Unpacking bootstrapper... Unpacking payload... Extracting ca-certificates-2026.4.22-hbd8a1cb_0.conda Extracting libgomp-15.2.0-he0feb66_19.conda Extracting libzlib-1.3.2-h25fd6f3_2.conda [ ... snip ... ] Linking conda-package-handling-2.4.0-pyh7900ff3_2 Linking conda-26.3.2-py313h78bf25f_1 Transaction finished installation finished.

为当前 shell 激活 Miniforge3：

~/miniforge3/bin/conda init

输出节选（注意最后一行会修改~/.bashrc）：

no change /home/even/miniforge3/condabin/conda no change /home/even/miniforge3/bin/conda no change /home/even/miniforge3/bin/activate no change /home/even/miniforge3/bin/deactivate no change /home/even/miniforge3/etc/profile.d/conda.sh no change /home/even/miniforge3/etc/fish/conf.d/conda.fish no change /home/even/miniforge3/shell/condabin/Conda.psm1 no change /home/even/miniforge3/shell/condabin/conda-hook.ps1 no change /home/even/miniforge3/lib/python3.13/site-packages/xontrib/conda.xsh no change /home/even/miniforge3/etc/profile.d/conda.csh modified /home/even/.bashrc ==> For changes to take effect, close and re-open your current shell. <==

改动将在重新打开 shell 后生效。

2. 创建并激活专用 Conda 环境

Conda 环境相当于独立的软件工作区，其中的包不会与其他环境互相干扰。为本工作坊创建名为gdal-cli-workshop的环境，并使用conda-forge渠道获取社区最新官方版本（若使用 Miniforge3 安装，该渠道通常已默认配置）：

conda create -y --name gdal-cli-workshop -c conda-forge

输出节选：

Retrieving notices: done Channels: - conda-forge Platform: linux-64 Collecting package metadata (repodata.json): done Solving environment: done ## Package Plan ## environment location: /home/even/miniforge3/envs/gdal-cli-workshop Downloading and Extracting Packages: Preparing transaction: done Verifying transaction: done Executing transaction: done # # To activate this environment, use # # $ conda activate gdal-cli-workshop # # To deactivate an active environment, use # # $ conda deactivate

激活环境：

conda activate gdal-cli-workshop

环境激活后，shell 提示符前缀会变为(gdal-cli-workshop)，用于提示当前所处的环境。

3. 安装 libgdal 与 gdal

GDAL 的安装被拆分为两个角色互补的包：

• libgdal元包：安装libgdal-core及大多数可选驱动插件（如libgdal-jp2openjpeg等），即 C/C++ 库本体；
• gdal包：提供 Python 绑定与命令行脚本。

(gdal) $ conda install -y -c conda-forge libgdal gdal

输出节选：

Channels: - conda-forge Platform: linux-64 Collecting package metadata (repodata.json): done Solving environment: done ## Package Plan ## environment location: /home/even/miniforge3/envs/gdal-cli-workshop added / updated specs: - gdal - libgdal The following packages will be downloaded: [ ... snip ... ] Downloading and Extracting Packages: Preparing transaction: done Verifying transaction: done Executing transaction: done

验证版本：

$ gdal --version

GDAL 3.13.1 "Iowa City", released 2026/06/01

macOS 平台安装

官方对 macOS 的说明相对简略（原因是缺乏该平台的实际测试环境），核心步骤如下：

1. 若尚无 Conda，请访问 conda-forge 官网下载页面，选择与你 CPU 架构匹配的安装器；
2. 安装完成后，完全沿用上述 Linux 平台的 Conda 步骤，包括创建gdal-cli-workshop环境、conda activate、conda install -y -c conda-forge libgdal gdal以及gdal --version验证。

Linux 与 macOS 的命令是通用的，唯一的差异在于安装器的 CPU 架构选择。

Windows 平台安装

Windows 安装（文档在 Windows 10 上验证，预计对 Windows 11 同样有效）分为四个阶段：安装独立 Miniforge3 → 创建专用 Conda 环境 → 安装 MSYS2 Bash 环境 → 配置gdal.bat启动脚本。为保证后续指令无需修改即可执行，请严格按文档推荐路径c:\gdal安装。

阶段一：以管理员身份安装独立的 Miniforge3

如果已有 Conda 安装，可跳过此阶段。不过强烈建议为工作坊安装一个独立的 Miniforge3 实例，理由有二：避免与你现有的 Conda 安装互相干扰；且只有使用默认位置，后续的启动脚本才能无需修改直接使用。

下载Miniforge3-Windows-x86_64.exe安装器（可从 conda-forge 官方 Miniforge 发布渠道获取），然后右键选择"以管理员身份运行"——管理员权限是为了确保你有权写入c:\gdal，以便后续指令按原样执行。随后按安装向导操作：

1. 确认 Welcome 对话框；
2. 接受许可协议；
3. 选择"Just Me"并确认；
4. 将安装路径修改为c:\gdal\miniforge3并确认（见上文第一张图）；
5. 高级选项中只勾选 "Create shortcuts"，点击 Install；
6. 安装完成后依次点击 Next、Finish。

阶段二：创建专用 Conda 环境（--prefix 方式）

从开始菜单选择 "Anaconda Prompt"（见上文第二张图），打开一个 Conda 可执行文件已加入 PATH 的cmd控制台。

与 Linux 使用--name不同，Windows 示例采用--prefix方式将环境显式创建到c:\gdal\condaenv\gdal：

(base) C:\Users\my_user_name>conda create -y --prefix c:/gdal/condaenv/gdal -c conda-forge

输出节选：

Retrieving notices: done Channels: - conda-forge - defaults Platform: win-64 Collecting package metadata (repodata.json): done Solving environment: done ## Package Plan ## environment location: c:\gdal\condaenv\gdal Downloading and Extracting Packages: Preparing transaction: done Verifying transaction: done Executing transaction: done # # To activate this environment, use # # $ conda activate c:\gdal\condaenv\gdal # # To deactivate an active environment, use # # $ conda deactivate

激活环境：

(base) C:\Users\my_user_name>conda activate c:\gdal\condaenv\gdal

阶段三：安装 GDAL

与 Linux 一致，同时安装库元包与 Python 绑定包：

(c:\gdal\condaenv\gdal) C:\Users\my_user_name>conda install -y -c conda-forge gdal libgdal

输出节选（Windows 平台 GDAL 相关组件总下载约 180.9 MB）：

Channels: - conda-forge - defaults Platform: win-64 Collecting package metadata (repodata.json): done Solving environment: done ## Package Plan ## environment location: c:\gdal\condaenv\gdal added / updated specs: - gdal - libgdal The following packages will be downloaded: package | build [ ... snip ... ] ------------------------------------------------------------ Total: 180.9 MB The following NEW packages will be INSTALLED: [ ... snip ... ] Downloading and Extracting Packages: Preparing transaction: done Verifying transaction: done Executing transaction: done

验证：

(c:\gdal\condaenv\gdal) C:\Users\my_user_name>gdal --version

GDAL 3.13.1 "Iowa City", released 2026/06/01

阶段四：安装 Bash shell（MSYS2）

gdal命令行带有强大的自动补全（auto-completion）机制，但这要求从 Bash 兼容 shell 中使用。因此需要安装 MSYS2。

下载 MSYS2 安装器（msys2-x86_64-*.exe，可从 msys2 官方发布渠道获取），右键"以管理员身份运行"。安装向导中：

1. 点击 Next；
2. 指定c:\gdal\msys64为安装目录并点击 Next（见上文第三张图）；
3. 指定 "msys2_gdal" 作为开始菜单文件夹名称并点击 Next；
4. 点击 Finish。

阶段五：创建 gdal.bat 启动脚本

下载工作坊启动脚本并保存为c:\gdal\gdal.bat。该脚本会启动一个 Bash shell，并加载运行 GDAL 所需的全部环境，包括命令行补全。仓库内即保存了这份脚本的原始版本：doc/source/workshop/gdal.bat，其逐行逻辑如下：

@call C:\gdal\miniforge3\condabin\conda activate c:\gdal\condaenv\gdal @set "OUTFILE=C:\gdal\.bashrc" @echo export PATH=/c/gdal/condaenv/gdal/Library/bin:/c/gdal/miniforge3/Scripts:/c/gdal/msys64/usr/bin:^$PATH> "%OUTFILE%" @echo source /c/gdal/condaenv/gdal/Library/share/bash-completion/completions/gdal>> "%OUTFILE%" @set "PS1=(gdal) \w\$ " @call C:\gdal\msys64\usr\bin\bash.exe --init-file C:\gdal\.bashrc

各行含义：

注意：该启动脚本仅在 Miniforge3 与 Conda 环境都安装在上述默认位置时才直接可用。若安装位置不同，需要编辑脚本中对应的路径。

从资源管理器或创建的快捷方式启动c:\gdal\gdal.bat，然后验证补全。输入（<TAB>表示按 TAB 键）：

gdal --<TAB><TAB>

应看到如下候选选项：

--config --drivers --help --json-usage --version

补全功能之所以能工作，是因为gdal二进制内置了一个隐藏的completion子命令，Bash 补全脚本通过调用它实时生成候选列表（详见 apps/gdal.cpp 中EmitCompletion()与main()对completion参数的处理）。除顶层选项外，它还支持子命令列表补全、参数值补全（如--of=<TAB>给出json/text）、EPSG CRS 代码补全（如EPSG:432<TAB>列出 4326 WGS 84 等）、乃至云端文件名补全（如/vsis3/...），完整示例见 Bash 补全官方文档。

获取工作坊使用的示例数据集

下载工作坊数据集压缩包master.zip（超过 1 GB），并解压到你选择的目录。数据源为gdal_cli_workshop_data仓库。

Linux/macOS 示例：

mkdir $HOME/gdal_cli_workshop_data cd $HOME/gdal_cli_workshop_data curl -O <master.zip 下载地址> unzip master.zip

Windows：下载并解压文件后，需要把工作目录切换到解压出的文件夹再运行练习。例如解压到C:\gdal\gdal_cli_workshop_data-master时，在启动脚本打开的命令行中执行：

(gdal) /c/gdal$ cd gdal_cli_workshop_data-master

数据集的构成与一个"降精度"细节

数据集包含 GRIB/NetCDF 气象栅格、Sentinel-2 SAFE 影像目录、DEM、矢量行政区划、OSM 数据与配置文件等（完整清单见上文 Docker 一节的ls -al输出）。

文档特别提示了一个工程细节：为满足 GitHub 单文件 100 MB 上限，Sentinel-2 原始数据中的个别文件被移除，且T34TDR_.../IMG_DATA/R10m/T34TDR_20260423T094029_B08_10m.jp2被降精度重处理以压缩到 100 MB 以内。该重处理使用的正是新 CLI 的栅格转换命令：

gdal raster convert --of JP2OpenJPEG --creation-option QUALITY=45 --co BLOCKXSIZE=1024 --co BLOCKYSIZE=1024

这同时也是一个很好的新 CLI 语法示例：--of指定输出格式，--creation-option（可简写--co）传入驱动级创建选项。

配套工具安装

安装 jq（JSON 处理工具）

新 CLI 大量使用 JSON 输出（如gdal raster info --of json），因此工作坊要求安装jq。在 Conda 启用的 shell 中：

conda install -y -c conda-forge jq

强烈推荐：安装 QGIS 用于可视化

• Linux 与 Windows：在 Conda 启用的 shell 中安装，QGIS 与 GDAL 同环境可保证版本匹配：

conda install -y -c conda-forge qgis

额外下载约 1.3 GB，解压后预计占用约 2 GB 空间。

• macOS 例外：QGIS 的 Conda 构建目前不适用于 macOS，请从 QGIS 官方网站下载 macOS 安装器。

文本编辑器

准备一个顺手的基础文本编辑器，用于准备和粘贴命令行，以及查看 JSON 输出。

进阶：使用 GDAL 开发版构建（gdal-master 渠道）

希望抢先体验 GDAL 主线开发分支（master）最新状态、且能承受一定风险的进阶用户，可以使用gdal-masterConda 渠道获取每日构建，说明见 GDAL 下载页 的 "GDAL master Conda builds" 一节。典型用法：

conda install -c gdal-master -c conda-forge gdal-master::gdal

与发布版一致，额外驱动可通过gdal-master::libgdal-{driver_name}形式安装，例如gdal-master::libgdal-arrow-parquet。

环境里已装过 master 构建、需要升级到最新版本时，注意 GDAL 子包可能需要逐个更新——因为 master 的版本号（如3.12.99）不会随每次夜间构建变化：

# 检查当前已安装的 GDAL 组件与版本 conda list gdal gdal --version # 移除当前 master 版本 conda remove gdal libgdal-core --yes # 安装最新的 GDAL master 构建 conda install -c gdal-master -c conda-forge gdal libgdal-core --yes gdal --version

需要提醒的是：master 构建基于 conda-forge 依赖，其行为可能领先于本文所述的 3.13.1 稳定版，如与工作坊练习预期不符，请回到稳定版环境。

原理印证：新 CLI 与补全能力的源码实现

为帮助理解"为什么这样装、补全从哪里来"，这里从仓库源码层面印证几个关键点：

• gdal主程序入口位于 apps/gdal.cpp：main()先处理早期配置项（含--config-options-in-stdin等特殊开关），随后通过GDALGlobalAlgorithmRegistry::GetSingleton().Instantiate(...)实例化根算法、调用GDALAllRegister()注册全部驱动、ParseCommandLineArguments()解析参数，最后执行alg->Run(...)与Finalize()。
• 补全的后端机制同样在 apps/gdal.cpp：当第一个参数是completion时，程序进入EmitCompletion()分支，把候选选项以空格分隔写到 stdout；scripts/gdal-bash-completion.sh（由completionFinder.py自动生成）正是通过调用gdal completion ...拿到候选并完成<TAB>补全的。这也是 Windows 安装 MSYS2 Bash 的根本原因。
• gdal.bat 与补全文件的关联：启动脚本中的source .../Library/share/bash-completion/completions/gdal对应的就是上面这份自动生成脚本在安装后的落盘位置，三者形成完整闭环：脚本 →gdal completion→ 候选列表 → 交互补全。

安装校验清单

完成以上任一路线后，建议按如下清单逐项自检：

常见问题快速定位：

• Docker 下 QGIS 无窗口：检查是否执行了xhost +local:root，以及-v /tmp/.X11-unix:/tmp/.X11-unix挂载；
• Windows 下gdal.bat报路径错误：确认 Miniforge3 与 Conda 环境是否安装在默认位置（c:\gdal与c:\gdal\condaenv\gdal），否则编辑脚本路径；
• Windows 下安装器写不进去c:\gdal：务必以管理员身份运行安装器；
• macOS 安装 QGIS：走 QGIS 官方安装器而非 Conda。

完成上述环境准备后，即可进入 工作坊首节内容，从gdal raster info与gdal vector info开始探索新 CLI 的完整能力。

• GIS
• 遥感
• 数据工程