QGIS: DLL load failed importing _gdal (resuelto)
Publicado el Actualizado el
ImportError: DLL load failed while importing _gdal rompe cualquier Python que ejecute from osgeo import gdal dentro de QGIS en Windows, incluido Processing Toolbox. Hay una segunda copia de GDAL antes que la de QGIS en PATH, así que elimina esas carpetas que no son de QGIS y después cierra sesión de Windows y vuelve a entrar. En la mayoría de los equipos esa es toda la solución, y las cuatro siguientes cubren el resto.
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 eliminó esa ayuda de tres líneas en la versión 3.7.0, así que en una instalación actual solo aparece la primera línea. En algunos equipos cambia una palabra, pero la causa es la misma:
ImportError: DLL load failed while importing _gdal: The specified procedure could not be found.
La mayoría de la gente nunca lee ninguna de las dos versiones. Se encuentra con el fallo como una sola línea en el panel Log Messages de QGIS y con un menú Processing vacío:
Couldn't load plugin 'processing'
Aplica a Windows, QGIS 3.16 y posteriores, y cualquier Python 3.8 o posterior que ejecute from osgeo import gdal.
La solución rápida
Enumera todas las carpetas de PATH que contienen una DLL de GDAL
Abre OSGeo4W Shell desde la carpeta de QGIS en el menú Start y ejecuta esto, que repite la lógica del propio GDAL:
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')))))"
Lee la línea primera. Esa es la carpeta que usa GDAL y debería estar dentro de tu instalación de QGIS. Conserva toda la salida, porque cada solución siguiente la utiliza.
Elimina las entradas que no sean de QGIS
Anaconda, Miniconda, una segunda instalación de QGIS u OSGeo4W, u otro paquete GIS. Abre Start, escribe "environment variables", abre Edit the system environment variables, después Environment Variables, luego Path y elimínalas. Cierra sesión de Windows y vuelve a entrar.
Inicia QGIS desde su propio acceso directo
No desde un shell en el que ya hayas ejecutado el script activate de otro entorno. Un shell que haya puesto una ruta de gdal-dev en primer lugar se la entrega directamente a QGIS.
Comprueba que funciona
En QGIS, abre Plugins y después Python Console, y ejecuta:
from osgeo import gdal
print(gdal.__version__)
Un número de versión sin ningún traceback encima significa que se cargaron las DLL correctas. Abre también el menú Processing, porque Toolbox vuelve en cuanto el plugin processing puede importar GDAL, y un menú Processing vacío significa que todavía no has terminado.
Solución 2: ejecuta tu script dentro del entorno de QGIS
El paso 1 no mostró nada. Ninguna carpeta de PATH contiene una DLL de GDAL, así que nunca se registró ninguna, y eso ocurre cuando un python.exe normal o una configuración de ejecución de PyCharm se inicia fuera del entorno de QGIS. Ejecuta el script en OSGeo4W Shell o mediante python-qgis.bat en la carpeta bin de QGIS. En una instalación de versión de soporte prolongado, ese archivo se llama python-qgis-ltr.bat. Cualquiera de los dos registra la carpeta de DLL correcta antes de que se inicie Python.
Si el error no cambia, ve a la Solución 3.
Solución 3: repara una instalación de OSGeo4W actualizada a medias
El paso 1 mostró varias líneas y todas están dentro del mismo árbol de OSGeo4W. Conservas gdal y gdal-dev de una actualización que se detuvo a mitad. Vuelve a ejecutar el instalador de OSGeo4W y reinstala los paquetes gdal y qgis, o reinstala QGIS desde el instalador independiente, que es la forma más rápida de salir del problema.
Si el error no cambia, ve a la Solución 4.
Solución 4: configura USE_PATH_FOR_GDAL_PYTHON
El paso 1 mostró una línea, la de QGIS, y la importación sigue fallando. Ahora vale la pena probar la variable, y solo ahora. En QGIS: Settings, después Options, luego System y finalmente el grupo Environment. Activa la casilla de variables personalizadas, añade este nombre y valor y reinicia QGIS:
USE_PATH_FOR_GDAL_PYTHON=YES
Ayuda a una pequeña minoría de personas, por la razón explicada en "Por qué ocurre".
Si el error no cambia, ve a la Solución 5.
Solución 5: conserva un GDAL por entorno de conda
Tu GDAL procede de conda. Usa únicamente conda-forge, en un entorno nuevo, y no mezcles una rueda de GDAL de pip en el mismo lugar. Un canal, una copia.
Si el error no cambia, envíame las tres cosas siguientes.
Por qué ocurre
Python 3.8 dejó de buscar DLL de extensiones en PATH. GDAL lo compensa en osgeo/__init__.py. Con USE_PATH_FOR_GDAL_PYTHON sin definir, GDAL lee PATH en orden, registra con os.add_dll_directory() la primera carpeta que contiene una gdal*.dll o libgdal*.dll y deja de buscar. Por tanto, gana el GDAL que aparece antes en PATH y, cuando esa copia no es la de QGIS, sus DLL no coinciden con el módulo _gdal contra el que se compiló QGIS.
Configurar la variable amplía esa búsqueda en lugar de limitarla, porque GDAL registra entonces todas las carpetas de PATH y no aplica ningún glob. Por eso la línea que antes mostraba el mensaje de error ayuda a casi nadie.
Nuestro AI Segmentation plugin lee raster mediante el GDAL que QGIS ya incluye y no instala ninguno propio, así que funciona en cuanto lo hace la importación anterior. El resto de lo que desarrollamos para QGIS está en la página QGIS AI.
¿Sigue sin funcionar?
Envíame tres cosas: tu versión de QGIS, el traceback completo y la salida de la comprobación de PATH del paso 1 de la solución rápida. Mi dirección es stephane.barbot@terra-lab.ai. La primera línea de esa salida suele bastar para saber en cuál de los cinco casos estás.
Preguntas frecuentes
¿Por qué mi error no menciona USE_PATH_FOR_GDAL_PYTHON?
GDAL eliminó esas tres líneas de ayuda en la versión 3.7.0, así que cualquier versión actual muestra la primera línea y nada más. La causa no cambió. La solución es la misma que habrías aplicado en la versión 3.6.
¿Configurar USE_PATH_FOR_GDAL_PYTHON=YES lo soluciona?
Rara vez, y es la Solución 4 en lugar de la Solución 1 por una razón. La variable hace que GDAL registre todas las carpetas de PATH en vez de la primera que contiene una DLL de GDAL, lo que amplía la búsqueda en lugar de dirigirla a QGIS. Pruébala cuando PATH muestre una sola carpeta de GDAL y la importación siga fallando.
¿Por qué desapareció Processing Toolbox al mismo tiempo?
El plugin processing importa GDAL, así que no puede cargarse, y QGIS escribe "Couldn't load plugin 'processing'" en el panel Log Messages. Toolbox vuelve por sí solo cuando la importación funciona, por lo que es la forma más rápida de comprobar si una solución se aplicó.
¿Qué ocurre si el traceback dice _C en lugar de _gdal?
Es un módulo distinto y requiere otra solución. Tiene su propio artículo: DLL load failed while importing _C.
