GeoDjangoのGDAL・GEOSエラー原因｜本番デプロイの確認手順

ローカル環境では動いていたGeoDjangoを本番サーバーやコンテナへデプロイすると、Could not find the GDAL libraryやGEOSの読み込みエラーが発生することがあります。

GeoDjangoはPythonパッケージだけでは動きません。GDAL、GEOS、PROJなどのネイティブライブラリがOS側に必要です。Pythonの依存関係をインストールしても、実行環境に共有ライブラリがなければ起動時に失敗します。

先に結論

次の順番で切り分けます。

1. エラーがGDAL、GEOS、PROJ、PostGISのどこで発生しているか確認する
2. 実行中のコンテナやサーバーにOSライブラリがあるか確認する
3. コマンドとGeoDjangoの両方からバージョンを確認する
4. 動的リンカーが共有ライブラリを見つけられるか確認する
5. 自動検出できない場合だけライブラリパスを設定する
6. ビルド環境と実行環境の差をなくす

エラーメッセージに表示された候補バージョンを見て、Python設定へパスを適当に追加するだけでは再発します。実際にインストールされたファイルと、アプリを動かしている環境を確認します。

よくある症状

GDALが見つからない

django.core.exceptions.ImproperlyConfigured:
Could not find the GDAL library

GDAL自体がない、共有ライブラリだけがない、または動的リンカーの検索パスに含まれていない場合に発生します。

GEOSが見つからない

OSError: libgeos_c.so: cannot open shared object file

GEOSのC API共有ライブラリがない、あるいは実行環境から参照できない状態です。

ローカルでは動くが本番だけ失敗する

開発PCにはHomebrewやOSパッケージでGDALが入っている一方、本番イメージにはPython依存だけを入れている場合によく起きます。

マルチステージビルドでは、ビルドステージにだけライブラリを入れ、実行ステージへ必要な共有ライブラリを含め忘れることがあります。

まず実行環境へ入って確認する

確認コマンドは、ホストOSではなく、実際にDjangoを動かしているコンテナやサーバー内で実行します。

gdalinfo --version
geos-config --version
projinfo --version

コマンドが見つからない場合は、対応するOSパッケージが不足しています。コマンドが動いても、Pythonプロセスが共有ライブラリを読めるとは限らないため、次にGeoDjangoから確認します。

python -c "from django.contrib.gis.gdal import GDAL_VERSION; print(GDAL_VERSION)"

GEOSも読み込めるか確認します。

python -c "from django.contrib.gis.geos import geos_version; print(geos_version())"

ここで同じエラーが出れば、アプリ固有の処理ではなく、GeoDjangoの起動前提に問題があります。

OSパッケージを確認する

Debian系のコンテナでは、構成に応じて次のようなパッケージが必要です。

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        gdal-bin \
        libgdal-dev \
        libgeos-dev \
        proj-bin \
    && rm -rf /var/lib/apt/lists/*

パッケージ名はOSとバージョンによって異なります。Alpine Linux、Amazon Linux、Red Hat系では別の名前になります。利用中のベースイメージのパッケージ一覧を確認してください。

ビルドにヘッダーファイルが必要でも、実行時にはランタイムライブラリだけでよい場合があります。ただし、最適化のためにパッケージを削るのは、動作確認後に進めます。

共有ライブラリの場所を確認する

Linuxでは、次のようなコマンドで動的リンカーが認識しているライブラリを確認できます。

ldconfig -p | grep -E "gdal|geos"

環境によってldconfigがない場合は、パッケージ管理システムやfindで実ファイルを確認します。

find /usr -name "libgdal.so*" -o -name "libgeos_c.so*"

ファイルが存在しても、プロセスのアーキテクチャと一致しない場合や、依存する別ライブラリが不足している場合は読み込めません。

ldd /usr/lib/x86_64-linux-gnu/libgdal.so

not foundが表示された依存ライブラリがあれば、そのパッケージを追加します。実際のパスは環境ごとに異なるため、確認したファイルを指定します。

GDAL_LIBRARY_PATHとGEOS_LIBRARY_PATH

GeoDjangoが自動検出できない場合は、Django設定へライブラリの絶対パスを指定できます。

GDAL_LIBRARY_PATH = "/usr/lib/x86_64-linux-gnu/libgdal.so"
GEOS_LIBRARY_PATH = "/usr/lib/x86_64-linux-gnu/libgeos_c.so"

この設定は最後の手段です。存在しないパスや、開発PCだけのパスを固定すると、環境更新のたびに壊れます。

指定する前に次を確認します。

• 実行環境にそのファイルが存在する
• シンボリックリンクの参照先が存在する
• アプリのアーキテクチャと一致する
• 依存する共有ライブラリも解決できる

コンテナでは、OSパッケージを正しく入れ、自動検出できる状態にするほうが保守しやすい場合が多くあります。

GDAL・GEOS・PROJの組み合わせを確認する

ネイティブライブラリは互いに依存しています。異なる配布元から部分的にインストールすると、バージョンの組み合わせで問題が起きることがあります。

gdalinfo --version
geos-config --version
projinfo --version
python -c "import django; print(django.get_version())"

利用バージョンをデプロイログへ残しておくと、ベースイメージ更新後に発生した問題を比較できます。

latestタグだけに依存せず、動作確認したOSイメージと主要パッケージのバージョンを固定します。セキュリティ更新時は、ステージング環境でGIS処理を確認してから本番へ反映します。

PostGIS接続時の確認

GeoDjangoが起動しても、PostGIS拡張が有効でなければ空間フィールドや関数を使えません。

SELECT PostGIS_Full_Version();

拡張が未作成の場合は、権限を持つユーザーが対象データベースで作成します。

CREATE EXTENSION IF NOT EXISTS postgis;

本番環境では、アプリ用ユーザーへ拡張作成権限を付けない構成が一般的です。データベース管理者やマイグレーション用の権限で事前に作成します。

Dockerで起きやすい見落とし

ビルドステージにしか入っていない

FROM python:3.12-slim AS builder
# ここにGDALを入れても

FROM python:3.12-slim AS runtime
# runtimeへ必要な共有ライブラリがなければ動かない

最終イメージへ必要なランタイムライブラリを入れます。ビルド成功だけでなく、最終イメージからGeoDjangoをimportするテストを行います。

CPUアーキテクチャが違う

Apple Silicon上で作ったイメージと本番のアーキテクチャが異なる場合、ネイティブライブラリの問題が表面化することがあります。CIで本番と同じプラットフォーム向けにビルドします。

起動時に初めてエラーが分かる

コンテナのヘルスチェックやCIで、次の確認を行います。

python -c "from django.contrib.gis.gdal import GDAL_VERSION; print(GDAL_VERSION)"
python -c "from django.contrib.gis.geos import geos_version; print(geos_version())"
python manage.py check

アプリへトラフィックが到達する前に、GISライブラリの不足を検出できます。

本番デプロイのチェックリスト

• 実行環境内でGDAL、GEOS、PROJのバージョンを確認した
• GeoDjangoからGDALとGEOSをimportできる
• 共有ライブラリの依存先にnot foundがない
• 最終コンテナイメージにランタイムライブラリがある
• ベースイメージと主要バージョンを記録している
• PostGIS拡張が対象データベースで有効になっている
• ステージングで空間検索と座標変換を確認した
• ライブラリパスを開発PC固有の値にしていない

起動確認だけでなく、ST_Intersectsを使う検索、座標変換、GeoJSON出力など、実際に利用する処理まで確認します。

GeoDjangoの本番構築をご相談ください

BitLightでは、GeoDjango、PostGIS、GDALを使ったGISシステムの環境構築、デプロイエラーの調査、データ処理まで支援しています。

ローカルでは動くものの本番だけ起動しない、コンテナを軽量化するとGIS処理が壊れるといった問題も、実行環境と依存関係を確認して切り分けます。GIS開発を無料相談する

参考資料

• Django: Installing GeoDjango
• Django: Installing Geospatial Libraries
• Django: Installing PostGIS
• Django: Deploying GeoDjango