QGIS: DLL Load Failed Importing _gdal (Solved)
Published Updated
ImportError: DLL load failed while importing _gdal breaks any Python that runs from osgeo import gdal inside QGIS on Windows, the Processing Toolbox included. A second copy of GDAL sits earlier on your PATH than the QGIS one, so take those non-QGIS folders out of PATH, then sign out of Windows and back in. On most machines that is the whole fix, and the four below cover the rest.
ImportError: DLL load failed while importing _gdal: The specified module could not be found.
On Windows, with Python >= 3.8, DLLs are no longer imported from the PATH.
If gdalXXX.dll is in the PATH, then set the USE_PATH_FOR_GDAL_PYTHON=YES environment variable
to feed the PATH into os.add_dll_directory().
GDAL dropped that three-line hint in version 3.7.0, so on a current install you get the first line alone. One word changes on some machines, and the cause is the same:
ImportError: DLL load failed while importing _gdal: The specified procedure could not be found.
Most people never read either wording. They meet the fault as one line in the QGIS Log Messages panel, and a Processing menu with nothing in it:
Couldn't load plugin 'processing'
Applies to Windows, QGIS 3.16 and later, and any Python 3.8 or newer that runs from osgeo import gdal.
The quick fix
List every folder on PATH that holds a GDAL DLL
Open the OSGeo4W Shell from the QGIS folder in the Start menu and run this, which repeats GDAL's own logic:
python -c "import os,glob;print('\n'.join(p for p in os.environ['PATH'].split(';') if p and (glob.glob(os.path.join(p,'gdal*.dll')) or glob.glob(os.path.join(p,'libgdal*.dll')))))"
Read the first line. That is the folder GDAL takes, and it should sit inside your QGIS install. Keep the whole output, every fix below reads from it.
Delete the entries that are not QGIS
Anaconda, Miniconda, a second QGIS or OSGeo4W install, another GIS bundle. Open Start, type "environment variables", open Edit the system environment variables, then Environment Variables, then Path, and delete them. Sign out of Windows and back in.
Start QGIS from its own shortcut
Not from a shell where you already ran another environment's activate script. A shell that put a gdal-dev path first hands it straight to QGIS.
Check it worked
In QGIS, open Plugins, then Python Console, and run:
from osgeo import gdal
print(gdal.__version__)
A version number with no traceback above it means the right DLLs loaded. Open the Processing menu too, because the Toolbox comes back the moment the processing plugin can import GDAL, and an empty Processing menu means you are not done yet.
Fix 2: run your script inside the QGIS environment
Step 1 printed nothing at all. No folder on your PATH holds a GDAL DLL, so nothing was ever registered, and that happens when a plain python.exe or a PyCharm run configuration starts outside the QGIS environment. Run the script in the OSGeo4W Shell instead, or through python-qgis.bat in the QGIS bin folder. On a long term release install that file is named python-qgis-ltr.bat. Either one registers the right DLL folder before Python starts.
If the error is unchanged, go to Fix 3.
Fix 3: repair a half-upgraded OSGeo4W install
Step 1 printed several lines and all of them sit inside the same OSGeo4W tree. You are carrying both gdal and gdal-dev from an upgrade that stopped halfway. Rerun the OSGeo4W installer and reinstall the gdal and qgis packages, or reinstall QGIS from the standalone installer, which is the quickest route out of it.
If the error is unchanged, go to Fix 4.
Fix 4: set USE_PATH_FOR_GDAL_PYTHON
Step 1 printed one line, the QGIS one, and the import still fails. Now the variable is worth a try, and only now. In QGIS: Settings, then Options, then System, then the Environment group. Tick the custom variables box, add this name and value, then restart QGIS:
USE_PATH_FOR_GDAL_PYTHON=YES
It helps a small minority of people, for the reason set out under "Why it happens".
If the error is unchanged, go to Fix 5.
Fix 5: keep one GDAL per conda environment
Your GDAL comes from conda. Take it from conda-forge only, in a fresh environment, and never mix a pip GDAL wheel into the same place. One channel, one copy.
If the error is unchanged, send me the three things below.
Why it happens
Python 3.8 stopped searching PATH for extension DLLs. GDAL works around that in osgeo/__init__.py. With USE_PATH_FOR_GDAL_PYTHON unset, GDAL reads PATH in order, registers the first folder holding a gdal*.dll or libgdal*.dll with os.add_dll_directory(), and stops looking. So the earliest GDAL on your PATH wins, and when that copy is not the QGIS one, its DLLs do not match the _gdal module QGIS built against.
Setting the variable widens that search instead of narrowing it, because GDAL then registers every folder on PATH and globs for nothing at all. The line the error message used to print therefore helps almost nobody.
Our AI Segmentation plugin reads rasters through the GDAL that QGIS already ships and installs none of its own, so it works the moment the import above does. The rest of what we build for QGIS sits on the QGIS AI page.
Still broken?
Send me three things: your QGIS version, the full traceback, and the output of the PATH check from step 1 of the quick fix. My address is stephane.barbot@terra-lab.ai. The first line of that output is usually enough to say which of the five cases you are in.
Questions people ask
Why does my error not mention USE_PATH_FOR_GDAL_PYTHON?
GDAL removed those three hint lines in version 3.7.0, so anything current prints the first line and nothing else. Nothing about the cause changed with it. The fix is the same one you would have applied on 3.6.
Does setting USE_PATH_FOR_GDAL_PYTHON=YES fix it?
Rarely, and it is Fix 4 rather than Fix 1 for a reason. The variable makes GDAL register every folder on PATH instead of the first one holding a GDAL DLL, which widens the search rather than pointing it at QGIS. Try it once your PATH shows one GDAL folder and the import still fails.
Why did my Processing Toolbox disappear at the same time?
The processing plugin imports GDAL, so it cannot load, and QGIS writes "Couldn't load plugin 'processing'" to the Log Messages panel. The Toolbox comes back on its own once the import works, which makes it the quickest way to see whether a fix landed.
What if the traceback says _C instead of _gdal?
That is a different module and a different fix. It has its own post: DLL load failed while importing _C.
