Ubuntu 20.04.4LTS下Python环境安装GDAL依赖问题咨询

核心原则：Python GDAL包的版本必须和系统层面安装的GDAL二进制版本完全一致，这是90%以上依赖报错的根源。Ubuntu 20.04官方源默认提供GDAL 3.0.4版本，完美适配Python 3.8，不需要手动编译高版本GDAL。

• 安装系统级GDAL依赖与二进制文件
  执行以下命令安装完整依赖，避免后续编译Python包时找不到头文件、链接库：

  sudo apt update
  sudo apt install -y gdal-bin libgdal-dev gcc g++ python3.8-dev
  

  安装完成后执行gdal-config --version，确认输出版本为3.0.4，后续Python包版本必须和这个值完全匹配。
• 配置编译环境变量
  执行以下命令导出GDAL头文件路径，避免pip安装时找不到对应文件：

  export CPLUS_INCLUDE_PATH=/usr/include/gdal
  export C_INCLUDE_PATH=/usr/include/gdal
  

  如果需要长期生效，将上述两行追加到~/.bashrc文件末尾，执行source ~/.bashrc加载配置即可。
• 在Poetry环境中安装对应版本的GDAL Python包
  不要直接执行无版本号的安装命令，必须指定和系统GDAL完全一致的版本：

  # 先清理之前安装失败的残留包
  poetry remove gdal
  # 安装版本匹配的GDAL包
  poetry add gdal==3.0.4
  

常见报错排查：

• 若提示error: command 'gcc' failed with exit status 1，先确认是否已经安装了gcc g++ python3.8-dev三个依赖包，再确认环境变量是否正确配置
• 若提示version mismatch类报错，先在虚拟环境内执行pip show gdal查看已安装的Python GDAL版本，和gdal-config --version输出的系统版本对比，不一致就卸载重装对应版本
• 不要在Poetry环境中混用conda安装的GDAL，会触发动态链接库冲突，直接用系统源提供的依赖即可

• 安装验证
  执行以下命令验证安装是否正常：

  poetry run python -c "from osgeo import gdal; print('GDAL install success, version:', gdal.__version__)"
  

  正常输出GDAL版本号即代表安装完成，无依赖冲突问题。

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