Docker环境下使用GDAL报错：No module named 'osgeo._gdal_array'

本地运行正常的GDAL应用，部署到Docker后出现以下错误：

ModuleNotFoundError: No module named 'osgeo._gdal_array'

复现示例文件 #

app.py #

from osgeo import gdal
    
filename = "test_image.tiff" 
ds = gdal.Open(filename)
array = ds.GetRasterBand(1).ReadAsArray()
print(f"array of {len(array)}")

requirements.txt #

GDAL==3.4.3
netCDF4==1.6.2
netifaces==0.11.0
numpy==1.23.5
Werkzeug==2.2.2

原Dockerfile #

FROM python:3.11

RUN apt-get update
RUN apt-get install -y gdal-bin libgdal-dev

RUN pip install --global-option=build_ext --global-option="-I/usr/include/gdal" GDAL==3.4.3

ENV CPLUS_INCLUDE_PATH=/usr/include/gdal
ENV C_INCLUDE_PATH=/usr/include/gdal

COPY requirements.txt .
RUN python -m pip install -r requirements.txt
WORKDIR /app
COPY . /app

CMD ["python3", "app.py"]

问题原因分析 #

1. 重复安装GDAL：Dockerfile中先单独通过pip安装GDAL，之后又通过requirements.txt再次安装，两次安装会导致文件覆盖或损坏，缺失_gdal_array模块。
2. 环境变量设置时机错误：环境变量在安装GDAL之后才设置，导致编译Python版GDAL时无法正确识别系统头文件路径，部分模块编译失败。
3. 系统GDAL与Python包版本不匹配：apt默认安装的gdal-bin和libgdal-dev版本可能与指定的Python GDAL包版本差异过大，引发兼容性问题。

修正后的Dockerfile #

FROM python:3.11

# 提前设置环境变量，确保编译时能获取GDAL头文件路径
ENV CPLUS_INCLUDE_PATH=/usr/include/gdal
ENV C_INCLUDE_PATH=/usr/include/gdal

# 安装与Python包版本兼容的系统GDAL依赖，清理缓存减小镜像体积
RUN apt-get update && apt-get install -y --no-install-recommends \
    gdal-bin=3.4.1+dfsg-1build4 \
    libgdal-dev=3.4.1+dfsg-1build4 \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
# 一次性安装所有依赖，避免重复安装GDAL
RUN pip install --global-option=build_ext --global-option="-I/usr/include/gdal" -r requirements.txt

WORKDIR /app
COPY . /app

CMD ["python3", "app.py"]

关键修改说明 #

• 提前设置CPLUS_INCLUDE_PATH和C_INCLUDE_PATH环境变量，确保pip编译GDAL时能正确找到系统头文件。
• 移除单独安装GDAL的步骤，通过requirements.txt统一管理依赖，避免重复安装冲突。
• 指定系统GDAL依赖的具体版本，与Python包的3.4.3保持小版本兼容（apt仓库中3.4.1与3.4.3兼容性足够）。
• 使用--no-install-recommends并清理apt缓存，减小镜像体积。

内容的提问来源于stack exchange，提问作者DeNasti