跳到內容

QGIS 3 外掛在 QGIS 4 載入失敗

要改哪些地方

M10專業約 60 分鐘

草稿|尚未在 QGIS 4 實機驗證

QGIS 4.0 在 2026-03-06 發布,最大的底層變化是核心改用 Qt6 框架。QGIS 3 的外掛裝到 QGIS 4,常見症狀有三種:

  • 外掛管理員裡根本看不到,或標示不相容。
  • 啟用時跳出 ImportError、AttributeError,錯誤訊息裡出現 PyQt5、QAction 或某個列舉值名稱。
  • 能啟用,但某個按鈕、對話框或排序功能一用就出錯。

第一種是 metadata 的版本範圍問題,後兩種是程式碼沒有跟上 Qt6/PyQt6 的改變。本單元依官方外掛庫的遷移說明、QGIS wiki 的遷移指南,以及 QGIS Hub Plugin 專案的 Qt6 遷移筆記整理。

  • 一支要遷移的外掛原始碼(自己的,或 03 外掛骨架 做的 Layer Counter)。先用 Git 或複製一份備份。
  • 一套 QGIS 4 安裝(Windows 用 OSGeo4W 安裝的版本,才有 OSGeo4W Shell 可以跑檢查腳本)。
  • 一套 QGIS 3(建議 3.44),用來確認改完之後在 QGIS 3 也還能跑。
  1. 改 metadata.txt 的版本範圍。要同時支援 QGIS 3 與 4:

    ; 測試狀態:未在 QGIS 4 實機執行
    qgisMinimumVersion=3.22
    qgisMaximumVersion=4.99

    只支援 QGIS 4 時寫 qgisMinimumVersion=4.0,最高版本可省略。舊文件建議加的 supportsQt6=True 已從 QGIS 核心移除、不再有作用,可以刪掉。

  2. 把所有 from PyQt5... 改成 from qgis.PyQt...。qgis.PyQt 是 QGIS 提供的相容層,在 QGIS 3 會指向 PyQt5,在 QGIS 4 指向 PyQt6,同一份程式兩邊都能 import。

  3. 在 QGIS 4 的 OSGeo4W Shell 下載並執行官方檢查腳本 pyqt5_to_pyqt6.py:

    終端機視窗
    :: 測試狀態:未在 QGIS 4 實機執行
    curl -LO https://raw.githubusercontent.com/qgis/QGIS/refs/heads/master/scripts/pyqt5_to_pyqt6/pyqt5_to_pyqt6.py
    pip install astpretty tokenize-rt
    python-qgis pyqt5_to_pyqt6.py "C:\path\to\your_plugin"

    腳本會掃描整個外掛資料夾並修改程式碼,所以一定要在備份或 Git 版本控制下執行,跑完用 diff 逐行看它改了什麼。wiki 提醒:腳本要在只有 Qt6、沒有 PyQt5 的環境執行,而且不保證抓到所有問題。

  4. 手動補上腳本可能漏掉的地方,最常見的是列舉值全名化(下一節「原理」有對照表)、QAction 的 import、QRegExp。

  5. 跑一次兩邊的測試:在 QGIS 4 與 QGIS 3 各啟用外掛,把每個按鈕、對話框、Processing 演算法都實際操作一遍。只在 QGIS 3 測過不夠,很多列舉值問題只有在 Qt6 下才會出現。

  6. 上傳新版本到官方外掛庫後,到該版本頁面的 Qt6 Check 分頁看自動檢查結果,見 05 發布到官方外掛庫。

官方外掛庫的規則:相容性由 qgisMinimumVersion 與選填的 qgisMaximumVersion 決定;沒寫最高版本時,視為相容到最低版本所屬大版本的結尾。兩個欄位任一個 ≥ 4.0,該版本就會列在 QGIS 4 的外掛清單。

metadata 設定 結果
qgisMinimumVersion=3.22、qgisMaximumVersion=4.99 QGIS 3.22 以上與 QGIS 4.x 都列出
qgisMinimumVersion=4.0、qgisMaximumVersion=4.99 只列在 QGIS 4.x
qgisMinimumVersion=3.22、qgisMaximumVersion=3.99 不列在 QGIS 4
qgisMinimumVersion=3.22、沒寫最高版本 只到 QGIS 3 結尾,QGIS 4 不載入

改 qgisMaximumVersion 只是讓 QGIS 4「願意載入」,程式能不能跑是另一回事。先把程式改好、測過,再放寬版本範圍。

PyQt5 允許把列舉值掛在類別底下直接寫(Qt.UserRole),PyQt6 只接受包含列舉型別名稱的全名,也不再把整數自動轉成列舉。這是遷移時改最多的地方。QGIS wiki 與 Hub Plugin 筆記列出的例子:

舊寫法(Qt5) 新寫法(Qt6,QGIS 3 新版也可用)
Qt.UserRole Qt.ItemDataRole.UserRole
QSizePolicy.Minimum QSizePolicy.Policy.Minimum
QMessageBox.Ok QMessageBox.StandardButton.Ok
Qgis.Critical Qgis.MessageLevel.Critical
Qgis.Success Qgis.MessageLevel.Success
QgsWkbTypes.PolygonGeometry QgsWkbTypes.GeometryType.PolygonGeometry
QgsMapLayer.VectorLayer QgsMapLayer.LayerType.VectorLayer

測試程式裡的假物件也要一起改:Hub Plugin 筆記提到,mock.error.return_value = 0 要改成 QNetworkReply.NetworkError.NoError,proxy.sort(0, 1) 的第二個參數要改成 Qt.SortOrder.DescendingOrder。

  • QAction 在 Qt6 從 QtWidgets 移到 QtGui。要兩邊相容,就用 try/except 兩段 import(03 外掛骨架 的範例即是)。
  • QRegExp 在 Qt6 移除,改用 QRegularExpression;不分大小寫用 QRegularExpression.PatternOption.CaseInsensitiveOption;setFilterRegExp() 改 setFilterRegularExpression();indexIn(s) != -1 改 regex.match(s).hasMatch()。
  • Qt6 沒有內建 webp 圖片外掛時,QPixmap 讀 .webp 會靜默回傳空圖。外掛有用到 webp 圖示或縮圖,要改用 PNG 或自行轉檔。

self.tr(f'…{name}…') 這種寫法,翻譯擷取工具 pylupdate 抓不到原始字串。改寫成 self.tr('…{name}…').format(name=…)。這不是 Qt6 才有的問題,但遷移時順手整理最省事。

上傳到 plugins.qgis.org 時會自動用 pyqgis4-checker 掃描,結果出現在版本頁的 Qt6 Check 分頁,列出要更新的檔案與行號。官方遷移說明寫的是「僅供參考、不會阻擋上傳與核准」;但 QGIS Hub Plugin 專案的遷移筆記記錄,它的 v0.7.0 曾因未全名化的列舉值(例如 Qgis.Success)被擋下。兩份文件說法不一致,最保險的做法是上傳前自己先跑過 pyqt5_to_pyqt6.py,把結果清乾淨。

如果外掛還要支援很舊的 QGIS 3(例如 3.22),某些全名列舉值在舊版不存在。實務做法是在一個相容模組裡「依名稱查找」:先找新寫法,找不到再退回舊名稱,讓原始碼本身不出現舊的列舉值寫法。06 讀一支真實外掛 拆解的外掛就是這樣處理。

PyQGIS 不在 PyPI 上,用虛擬環境開發時要加 --system-site-packages 才能 import 到 QGIS 安裝的 qgis 模組:

終端機視窗
# 測試狀態:未在 QGIS 4 實機執行
python3 -m venv .venv --system-site-packages

有 CI 的專案,可以用 Docker 映像 qgis/qgis:release-3_34 與 qgis/qgis:4.0 各跑一次測試(Hub Plugin 專案的做法);QGIS 官方也提供含 Qt6 版 QGIS 與檢查腳本的 pyqgis4-checker 映像。

症狀 原因 解法
QGIS 4 的外掛管理員看不到外掛 qgisMaximumVersion 沒寫或寫 3.99 改成 qgisMaximumVersion=4.99(程式已改好之後)
ModuleNotFoundError: No module named 'PyQt5' 程式直接 import PyQt5 一律改成 from qgis.PyQt.QtCore import … 等寫法
ImportError: cannot import name 'QAction' from 'qgis.PyQt.QtWidgets' Qt6 的 QAction 在 QtGui try/except 兩段 import
AttributeError: type object 'Qt' has no attribute 'UserRole' 列舉值沒寫全名 改成 Qt.ItemDataRole.UserRole,其餘同理
篩選、搜尋功能一用就出錯 仍使用 QRegExp 或 setFilterRegExp() 改用 QRegularExpression 與 setFilterRegularExpression()
QGIS 4 下圖示變成空白 圖檔是 webp,Qt6 讀不到 改用 PNG 或 SVG

本單元目前沒有對應影片。

  1. 對自己的外掛資料夾搜尋 PyQt5、QRegExp、exec_( 三個字串,列出出現位置。
    • 檢查方式:改完後三個字串在原始碼中都不再出現(註解除外)。
  2. 在備份上跑 pyqt5_to_pyqt6.py,用 Git diff 檢視修改。
    • 檢查方式:能逐一說明每處修改是哪一類(列舉值、import 位置、其他);有看不懂的修改就先不要提交。
  3. 在 QGIS 3.44 與 QGIS 4 各啟用一次外掛,執行每個功能。
    • 檢查方式:兩邊的 記錄訊息 Log Messages 面板的 Python 錯誤分頁都沒有新錯誤。