Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

GeoDjango on Windows says it could not find the GDAL library (WinError 126)

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

Short answer

GeoDjango needs the GDAL, GEOS and PROJ C libraries, and Windows does not ship them. Install GDAL with OSGeo4W, put its bin folder on PATH with GDAL_DATA and PROJ_LIB set, log out and in, or give Django the full path to the library in GDAL_LIBRARY_PATH.

  • Applies to Django 5.2, GDAL 3.x via OSGeo4W, Python 3.12, Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out whether any GDAL DLL exists on the machine and whether its folder is on PATH.

    where gdal*.dll
    echo %PATH%
  2. 2Match what you see, then jump to its fix

    1. 1where finds no gdal DLL, or the folder is missing from PATHGDAL is not installed, or its bin folder is not on PATHFix
    2. 2The DLL exists (dir finds it), but the error staysThe library is installed in a place Django does not searchFix
    3. 3Django finds a library but GIS features fail, or the installer gave you a much newer or older GDALThe GDAL version is one Django does not supportFix

What does the error look like?

  • django.core.exceptions.ImproperlyConfigured: Could not find the GDAL library
  • OSError: [WinError 126] The specified module could not be found

Cause 1 of 3

GDAL is not installed, or its bin folder is not on PATH

1Check

Django's Windows route is the OSGeo4W installer, using the Express Web-GIS Install with the GDAL package selected. The libraries land under C:\OSGeo4W unless you changed it.

dir C:\OSGeo4W\bin\gdal*.dll

2Fix

Run the installer, then set the variables as Django documents, from an administrator command prompt. Restart or log out and back in so the new variables take effect.

set OSGEO4W_ROOT=C:\OSGeo4W
set GDAL_DATA=%OSGEO4W_ROOT%\apps\gdal\share\gdal
set PROJ_LIB=%OSGEO4W_ROOT%\share\proj
set PATH=%PATH%;%OSGEO4W_ROOT%\bin
reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%"
reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%"
reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%"

3Verify

In a new terminal, import the GDAL wrapper through Django.

python -c "import django, os; os.environ['DJANGO_SETTINGS_MODULE']='mysite.settings'; django.setup(); from django.contrib.gis import gdal; print(gdal.gdal_version())"

Confirmed by docs.djangoproject.com

Did this fix it?

Cause 2 of 3

The library is installed in a place Django does not search

1Check

If GDAL lives in a non-standard location, or you would rather not change the system path, Django accepts the library location directly.

dir C:\OSGeo4W\bin\gdal*.dll

2Fix

Set GDAL_LIBRARY_PATH in settings.py to the full path of the DLL you found. Do the same with GEOS_LIBRARY_PATH if Django then complains about GEOS, and use the C library file (geos_c).

# settings.py
GDAL_LIBRARY_PATH = r"C:\OSGeo4W\bin\gdal310.dll"
GEOS_LIBRARY_PATH = r"C:\OSGeo4W\bin\geos_c.dll"

3Verify

Start Django and import the GIS module.

python manage.py check

Confirmed by docs.djangoproject.com

Did this fix it?

Cause 3 of 3

The GDAL version is one Django does not support

1Check

Django 5.2 lists GDAL 3.1 up to 3.10 as supported. Check the version of the DLL you point at.

gdalinfo --version

2Fix

Install a GDAL version from the supported list, and match the DLL name in GDAL_LIBRARY_PATH to it.

# pick a supported GDAL (3.1 - 3.10 for Django 5.2) in the OSGeo4W installer

3Verify

Run the version check again.

python manage.py shell -c "from django.contrib.gis import gdal; print(gdal.gdal_version())"

Confirmed by docs.djangoproject.com

Did this fix it?

How do I stop it coming back?

  • Keep the OSGeo4W path and GDAL_LIBRARY_PATH in your project README so a new machine is set up the same way.
  • Set GDAL_LIBRARY_PATH from an environment variable, so one settings file works on every developer machine.
  • Check the supported GDAL list before you upgrade Django or the OSGeo4W packages.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.