GeoDjango on Windows says it could not find the GDAL library (WinError 126)
django.core.exceptions.ImproperlyConfigured: Could not find the GDAL libraryShort 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.
Fix it fast
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%2Match what you see, then jump to its fix
- 1
where finds no gdal DLL, or the folder is missing from PATHGDAL is not installed, or its bin folder is not on PATHFix - 2
The DLL exists (dir finds it), but the error staysThe library is installed in a place Django does not searchFix - 3
Django 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
- 1
What does the error look like?
django.core.exceptions.ImproperlyConfigured: Could not find the GDAL libraryOSError: [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*.dll2Fix
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
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*.dll2Fix
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 checkConfirmed by docs.djangoproject.com
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 --version2Fix
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 installer3Verify
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
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
asyncpg InterfaceError: another operation is in progress with SQLAlchemy
InterfaceError raised from a FastAPI endpoint that runs several queries at once
A single database connection can run one operation at a time.
4 causes, each with a fixDatabases
Django cannot load MySQLdb and asks whether mysqlclient is installed
Error loading MySQLdb module: Did you install mysqlclient or MySQL-python?
Django's MySQL backend imports MySQLdb, which is provided by the mysqlclient package.
3 causes, each with a fixDatabases
python manage.py migrate finishes but the tables for my app are missing
relation "myapp_book" does not exist
migrate only applies migration files that exist.
3 causes, each with a fixDatabases
Django save fails on PostgreSQL: null value in a column violates a not-null constraint
django.db.utils.IntegrityError: null value in column "price" of relation "shop_product" violates not-null constraint
A model field is NOT NULL in the database unless it has null=True.
3 causes, each with a fixDatabases
Django migration on PostgreSQL stops with 'pending trigger events'
django.db.utils.OperationalError: cannot ALTER TABLE "mytable" because it has pending trigger events
PostgreSQL runs a Django migration in one transaction.
2 causes, each with a fix