django/django · critical · ImproperlyConfigured

Could not find the GDAL library (tried "%s"). Is GDAL instal

Error message

Could not find the GDAL library (tried "%s"). Is GDAL installed? If it is, try setting GDAL_LIBRARY_PATH in your settings.

What it means

Raised as ImproperlyConfigured at import time when ctypes.util.find_library() returned None for every candidate name in libgdal.lib_names (and GDAL_LIBRARY_PATH was not set). The list tried includes versioned names up to gdal3.13.0 / gdal313 on Windows; newer or differently-named builds will not be auto-discovered.

Source

Thrown at django/contrib/gis/gdal/libgdal.py:66

        "gdal3.7.0",
        "gdal3.6.0",
        "gdal3.5.0",
        "gdal3.4.0",
        "gdal3.3.0",
    ]
else:
    raise ImproperlyConfigured('GDAL is unsupported on OS "%s".' % os.name)

# Using the ctypes `find_library` utility to find the
# path to the GDAL library from the list of library names.
if lib_names:
    for lib_name in lib_names:
        lib_path = find_library(lib_name)
        if lib_path is not None:
            break

if lib_path is None:
    raise ImproperlyConfigured(
        'Could not find the GDAL library (tried "%s"). Is GDAL installed? '
        "If it is, try setting GDAL_LIBRARY_PATH in your settings."
        % '", "'.join(lib_names)
    )

# This loads the GDAL/OGR C library
lgdal = CDLL(lib_path)

# On Windows, the GDAL binaries have some OSR routines exported with
# STDCALL, while others are not. Thus, the library will also need to
# be loaded up as WinDLL for said OSR functions that require the
# different calling convention.
if os.name == "nt":
    from ctypes import WinDLL

    lwingdal = WinDLL(lib_path)

View on GitHub (pinned to ae25a40be0)

Solutions

Install GDAL system-wide: apt-get install -y libgdal-dev (Debian/Ubuntu) or dnf install gdal-devel (Fedora).
Set GDAL_LIBRARY_PATH in settings.py to the absolute path of libgdal.so (find it with gdal-config --libs or ldconfig -p | grep gdal).
Refresh the linker cache: sudo ldconfig, or ensure LD_LIBRARY_PATH includes the directory containing libgdal.so.
For conda, run inside the activated conda env so $CONDA_PREFIX/lib is on the loader path; on Windows add the GDAL bin dir to PATH and restart the shell.

Example fix

# settings.py
# before: GDAL not discoverable

# after
GDAL_LIBRARY_PATH = "/usr/lib/x86_64-linux-gnu/libgdal.so"

Defensive patterns

Strategy: validation

Validate before calling

import ctypes.util, os
def gdal_is_loadable():
    if os.environ.get('GDAL_LIBRARY_PATH') and os.path.exists(os.environ['GDAL_LIBRARY_PATH']):
        return True
    return any(ctypes.util.find_library(n) for n in ('gdal', 'GDAL'))
# assert gdal_is_loadable() before importing django.contrib.gis

Prevention

Bake GDAL into your base Docker image rather than installing it ad hoc.
Pin GDAL_LIBRARY_PATH in settings for reproducibility across environments.
Run ldconfig after installing libgdal so find_library can locate it.
Match the GDAL shared-library major version to what your Django expects.

When it happens

Trigger: GDAL is not installed; libgdal.so is present but not in the linker path (ldconfig not refreshed); a custom build installed to /opt or /usr/local without updating LD_LIBRARY_PATH; a new GDAL version whose soname is beyond the highest versioned name in lib_names; Windows where the DLL is not on PATH.

Common situations: Minimal Docker images (python:slim) missing libgdal; conda environments where GDAL lives under $CONDA_PREFIX/lib but the system loader does not look there; fresh GDAL upgrades (e.g. 3.14+) whose soname is not yet in Django's hardcoded list; Windows installs where GDAL was added but PATH was not restarted.

Related errors

AI-assisted analysis of django/django@ae25a40be0 (2026-08-06). Data as JSON: /api/errors/e7be7a0fd2bc0d61. Report an issue: GitHub.