QGIS DLL load failed while importing _gdal 錯誤修復
發布於 更新於
ImportError: DLL load failed while importing _gdal 會讓任何在 Windows 上於 QGIS 內執行 from osgeo import gdal 的 Python 失效，包括空間運算工具箱。您的 PATH 中有另一份 GDAL 位於 QGIS 版本之前，因此請移除那些非 QGIS 資料夾，然後登出 Windows 並重新登入。對大多數電腦來說，這就是完整修復方式，以下四種方法涵蓋其餘情況。
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 在 3.7.0 版移除了這三行提示，因此目前的安裝只會顯示第一行。有些電腦上的錯誤只會改變一個詞，但原因相同：
ImportError: DLL load failed while importing _gdal: The specified procedure could not be found.
大多數人根本不會閱讀這兩種錯誤文字。他們只會在 QGIS Log Messages 面板中看到一行錯誤，以及一個空無一物的「空間運算」選單：
Couldn't load plugin 'processing'
適用於 Windows、QGIS 3.16 及更新版本，以及任何執行 from osgeo import gdal 的 Python 3.8 或更新版本。
快速修復
列出 PATH 中所有含有 GDAL DLL 的資料夾
從「開始」選單的 QGIS 資料夾開啟 OSGeo4W Shell，執行以下指令。它會重複 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')))))"
閱讀 第一 行。那就是 GDAL 會採用的資料夾，而且它應該位於您的 QGIS 安裝目錄內。保留完整輸出，以下每個修復方式都會用到它。
刪除不是 QGIS 的項目
Anaconda、Miniconda、第二個 QGIS 或 OSGeo4W 安裝，以及其他 GIS 套件都可能造成問題。開啟「開始」，輸入「環境變數」，開啟「編輯系統環境變數」，接著依序開啟「環境變數」、「Path」，然後刪除這些項目。登出 Windows 並重新登入。
從 QGIS 自己的捷徑啟動 QGIS
不要從已經執行其他環境 activate 指令碼的 Shell 啟動。如果 Shell 將 gdal-dev 路徑放在最前面，就會直接把它交給 QGIS。
確認修復成功
在 QGIS 中開啟「外掛程式」，接著開啟「Python 主控台」，執行：
from osgeo import gdal
print(gdal.__version__)
如果上方沒有 traceback，且顯示版本號，就代表正確的 DLL 已載入。也請開啟「空間運算」選單，因為 processing 外掛能夠匯入 GDAL 後，工具箱就會恢復，而空白的「空間運算」選單表示問題尚未解決。
修復 2：在 QGIS 環境內執行您的指令碼
步驟 1 完全沒有輸出。PATH 中沒有任何資料夾含有 GDAL DLL，因此沒有任何 DLL 被註冊。當一般的 python.exe 或 PyCharm run configuration 在 QGIS 環境外啟動時，就會發生這種情況。請改在 OSGeo4W Shell 中執行指令碼，或透過 QGIS bin 資料夾中的 python-qgis.bat 執行。在長期版本（LTR）安裝中，該檔案名稱是 python-qgis-ltr.bat。兩者都會在 Python 啟動前註冊正確的 DLL 資料夾。
如果錯誤沒有改變，請前往修復 3。
修復 3：修復半升級的 OSGeo4W 安裝
步驟 1 列出了數行，而且全部位於同一個 OSGeo4W 樹狀目錄內。您同時保留了升級中途停止的 gdal 和 gdal-dev。重新執行 OSGeo4W installer 並重新安裝 gdal 和 qgis 套件，或使用 standalone installer 重新安裝 QGIS。後者是最快的解決方式。
如果錯誤沒有改變，請前往修復 4。
修復 4：設定 USE_PATH_FOR_GDAL_PYTHON
步驟 1 列出了一行，而且是 QGIS 的資料夾，但匯入仍然失敗。現在才值得嘗試這個變數。在 QGIS 中依序開啟「設定」→「選項」→「系統」，再開啟「環境」群組。勾選「使用自訂變數」，加入以下名稱和值，然後重新啟動 QGIS：
USE_PATH_FOR_GDAL_PYTHON=YES
少數人會因此解決問題，原因詳見「問題原因」。
如果錯誤沒有改變，請前往修復 5。
修復 5：每個 conda 環境只保留一份 GDAL
您的 GDAL 來自 conda。請只在全新的環境中從 conda-forge 安裝，並且不要在同一個位置混用 pip GDAL wheel。一個 channel，一份副本。
如果錯誤沒有改變，請傳送以下三項資料給我。
問題原因
Python 3.8 停止為 extension DLL 搜尋 PATH。GDAL 會在 osgeo/__init__.py 中繞過這個限制。當 USE_PATH_FOR_GDAL_PYTHON 未設定時，GDAL 會依順序讀取 PATH，透過 os.add_dll_directory() 註冊第一個含有 gdal*.dll 或 libgdal*.dll 的資料夾，然後停止搜尋。因此，PATH 中最前面的 GDAL 會勝出。如果那份 GDAL 不是 QGIS 的版本，它的 DLL 就不會符合 QGIS 建置時所使用的 _gdal 模組。
設定這個變數會擴大而不是縮小搜尋範圍，因為 GDAL 之後會註冊 PATH 上的每個資料夾，而且完全不使用 glob。因此，錯誤訊息過去列印的那行提示幾乎幫不上任何人。
我們的 AI Segmentation 外掛會透過 QGIS 已經提供的 GDAL 讀取網格資料，自己不安裝 GDAL，所以只要上面的匯入成功，它就能運作。我們為 QGIS 建置的其他內容位於 QGIS AI 頁面。
仍然無法修復？
請傳送三項資料給我：您的 QGIS 版本、完整 traceback，以及快速修復步驟 1 中 PATH 檢查的輸出。我的信箱是 stephane.barbot@terra-lab.ai。該輸出的第一行通常就足以判斷您屬於五種情況中的哪一種。
大家常問的問題
為什麼我的錯誤沒有提到 USE_PATH_FOR_GDAL_PYTHON？
GDAL 在 3.7.0 版移除了那三行提示，因此目前的版本只會列印第一行，其他內容都不會顯示。原因並沒有因此改變。您在 3.6 上會採用的修復方式仍然相同。
設定 USE_PATH_FOR_GDAL_PYTHON=YES 能解決問題嗎？
很少能，而且它被列為修復 4 而不是修復 1 是有原因的。這個變數會讓 GDAL 註冊 PATH 上的每個資料夾，而不是只註冊第一個含有 GDAL DLL 的資料夾。它會擴大搜尋範圍，不是將搜尋指向 QGIS。請先確認 PATH 只顯示一個 GDAL 資料夾，且匯入仍然失敗後再嘗試。
為什麼我的空間運算工具箱同時消失了？
processing 外掛會匯入 GDAL，因此無法載入，QGIS 也會在 Log Messages 面板中寫入 "Couldn't load plugin 'processing'"。匯入恢復後，工具箱會自行回來，因此這是確認修復是否生效最快的方法。
如果 traceback 顯示的是 _C 而不是 _gdal，該怎麼辦？
那是不同的模組，也需要不同的修復方式。它有自己的文章：DLL load failed while importing _C。
