本文详解在 Ubuntu 基础镜像的 Docker 容器中从源码编译 GDAL 时，解决 ModuleNotFoundError: No module named 'osgeo' 的根本原因与两种可靠方案，确保 gdal2tiles.py 等工具可正常运行。
本文详解在 ubuntu 基础镜像的 docker 容器中从源码编译 gdal 时，解决 `modulenotfounderror: no module named 'osgeo'` 的根本原因与两种可靠方案，确保 `gdal2tiles.py` 等工具可正常运行。
在 Docker 中从源码构建 GDAL 并启用 Python 绑定（即 osgeo 模块）是一个常见但易出错的任务。默认情况下，CMake 将 GDAL 安装到 /usr/local 目录下，而 Python 的 site-packages 路径通常不包含 /usr/local/lib/python3/dist-packages（尤其在精简版 Ubuntu 镜像中），导致 import osgeo 失败——这正是 gdal2tiles.py 启动时报错的根源。
✅ 推荐解决方案（二选一）
方案一：修改安装前缀（推荐，更干净）
将 GDAL 安装到系统级 Python 路径（如 /usr），避免路径冲突：
RUN cmake \
-DBUILD_PYTHON_BINDINGS=ON \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DGDAL_USE_PYTHON=ON \
..
RUN cmake --build . --config Release
RUN cmake --build . --config Release --target install✅ 优势：无需额外环境变量，兼容 python3 -m gdal 和所有 osgeo 工具；适用于多用户/生产环境。
⚠️ 注意：需确保构建用户对 /usr 有写权限（Docker 中通常满足）；若使用 --user 安装或非 root 用户，需改用方案二。
方案二：显式设置 PYTHONPATH
保留默认安装路径（/usr/local），通过环境变量引导 Python 查找模块：
RUN cmake -DBUILD_PYTHON_BINDINGS=ON -DCMAKE_BUILD_TYPE=Release .. RUN cmake --build . --config Release RUN cmake --build . --config Release --target install # 关键：添加 dist-packages 路径（注意 Python 版本匹配） ENV PYTHONPATH=/usr/local/lib/python3/dist-packages:$PYTHONPATH
✅ 优势：无需修改安装路径，适合快速验证或定制化部署。
⚠️ 注意：python3/dist-packages 中的 python3 需与容器中实际 Python 版本一致（如 python3.10）。可通过 python3 -c "import sys; print(sys.path)" 确认目标路径。
? 验证是否成功
构建完成后，在容器内执行以下命令确认：
立即学习“Python免费学习笔记（深入）”；
python3 -c "from osgeo import gdal; print(gdal.__version__)" gdal2tiles.py --help
若无报错且输出版本号与帮助信息，则绑定成功。
? 补充建议
- 建议显式启用 -DGDAL_USE_PYTHON=ON（部分 GDAL 版本必需）；
- 构建前安装依赖：apt-get update && apt-get install -y python3-dev python3-setuptools；
- 若使用 pyenv 或虚拟环境，请确保 cmake 链接到对应 Python 解释器（通过 -DPYTHON_EXECUTABLE=/path/to/python）。
两种方案均经过生产级 Docker 镜像验证，选择其一即可彻底解决 osgeo 导入失败问题。
