如何正确在 Docker 中构建 GDAL 源码并启用 Python 绑定

本文详解在 Ubuntu 基础镜像的 Docker 容器中从源码编译 GDAL 时，解决 ModuleNotFoundError: No module named 'osgeo' 的关键方法——通过合理配置安装路径或 Python 模块搜索路径。

本文详解在 ubuntu 基础镜像的 docker 容器中从源码编译 gdal 时，解决 `modulenotfounderror: no module named 'osgeo'` 的关键方法——通过合理配置安装路径或 python 模块搜索路径。

在 Docker 环境中从源码构建 GDAL（尤其是开发分支）时，即使 CMake 配置启用了 Python 绑定（-DBUILD_PYTHON_BINDINGS=ON），最终运行 gdal2tiles.py 或 import osgeo 仍常报错：

ModuleNotFoundError: No module named 'osgeo'

根本原因在于：GDAL 默认安装到 /usr/local（如 /usr/local/lib/python3/dist-packages/osgeo/），而系统 Python 解释器默认不会自动搜索 /usr/local/lib/python3/dist-packages（尤其在精简的 Docker 镜像中，site-packages 路径未被自动包含）。这导致 Python 找不到已安装的 osgeo 包。

✅ 两种经验证的可靠解决方案如下：

方案一：显式设置 PYTHONPATH（推荐用于隔离环境）

在 cmake --build . --target install 后，将 GDAL 的 Python 包路径加入环境变量：

立即学习“Python免费学习笔记（深入）”；

RUN cmake -DBUILD_PYTHON_BINDINGS=ON -DCMAKE_BUILD_TYPE=Release ..RUN cmake --build .RUN cmake --build . --target install# 关键：告知 Python 在此处查找模块ENV PYTHONPATH=/usr/local/lib/python3/dist-packages:$PYTHONPATH

✅ 优点：不侵入系统路径，兼容多版本 Python；适用于需保留 /usr/local 默认前缀的 CI/CD 场景。
⚠️ 注意：确保路径与实际 Python 版本匹配（如 python3.8 → /usr/local/lib/python3.8/dist-packages）；可通过 python3 -c "import site; print(site.getsitepackages())" 验证。

方案二：修改安装前缀至系统路径（推荐用于生产镜像）

直接让 GDAL 安装到 Python 默认搜索路径内（如 /usr）：

# 将安装目标设为 /usr，使 osgeo 自动落入系统 site-packagesRUN cmake -DBUILD_PYTHON_BINDINGS=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr ..RUN cmake --build .RUN cmake --build . --target install

✅ 优点：无需额外环境变量，import osgeo 开箱即用；符合 Linux 发行版惯例。
⚠️ 注意：需确保容器中有写入 /usr 的权限（Ubuntu 基础镜像默认允许）；若使用 --user 安装或非 root 用户，应改用方案一。

补充建议

• 验证安装：构建完成后，可在 Dockerfile 中添加测试命令：

  RUN python3 -c "from osgeo import gdal; print(gdal.__version__)"

• 依赖完整性：确保已安装 Python 开发头文件（如 python3-dev）和 NumPy（GDAL Python 绑定运行时依赖）：

  RUN apt-get update && apt-get install -y python3-dev python3-numpy

• CMake 版本兼容性：GDAL 3.8+ 推荐使用 CMake ≥ 3.16，旧版可能忽略部分绑定配置。

二者任选其一，即可彻底解决 osgeo 导入失败问题，让 gdal2tiles.py 及其他 GDAL Python 工具在 Docker 中稳定运行。