QGIS 3 外掛在 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 也還能跑。
操作步驟(QGIS 4)
Section titled “操作步驟(QGIS 4)”-
改
metadata.txt的版本範圍。要同時支援 QGIS 3 與 4:; 測試狀態:未在 QGIS 4 實機執行qgisMinimumVersion=3.22qgisMaximumVersion=4.99只支援 QGIS 4 時寫
qgisMinimumVersion=4.0,最高版本可省略。舊文件建議加的supportsQt6=True已從 QGIS 核心移除、不再有作用,可以刪掉。 -
把所有
from PyQt5...改成from qgis.PyQt...。qgis.PyQt是 QGIS 提供的相容層,在 QGIS 3 會指向 PyQt5,在 QGIS 4 指向 PyQt6,同一份程式兩邊都能 import。 -
在 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.pypip install astpretty tokenize-rtpython-qgis pyqt5_to_pyqt6.py "C:\path\to\your_plugin"腳本會掃描整個外掛資料夾並修改程式碼,所以一定要在備份或 Git 版本控制下執行,跑完用 diff 逐行看它改了什麼。wiki 提醒:腳本要在只有 Qt6、沒有 PyQt5 的環境執行,而且不保證抓到所有問題。
-
手動補上腳本可能漏掉的地方,最常見的是列舉值全名化(下一節「原理」有對照表)、
QAction的 import、QRegExp。 -
跑一次兩邊的測試:在 QGIS 4 與 QGIS 3 各啟用外掛,把每個按鈕、對話框、Processing 演算法都實際操作一遍。只在 QGIS 3 測過不夠,很多列舉值問題只有在 Qt6 下才會出現。
-
上傳新版本到官方外掛庫後,到該版本頁面的 Qt6 Check 分頁看自動檢查結果,見 05 發布到官方外掛庫。
版本範圍怎麼判斷
Section titled “版本範圍怎麼判斷”官方外掛庫的規則:相容性由 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「願意載入」,程式能不能跑是另一回事。先把程式改好、測過,再放寬版本範圍。
列舉值必須寫全名
Section titled “列舉值必須寫全名”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。
搬家與移除的類別
Section titled “搬家與移除的類別”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 或自行轉檔。
翻譯字串不要用 f-string
Section titled “翻譯字串不要用 f-string”self.tr(f'…{name}…') 這種寫法,翻譯擷取工具 pylupdate 抓不到原始字串。改寫成 self.tr('…{name}…').format(name=…)。這不是 Qt6 才有的問題,但遷移時順手整理最省事。
官方外掛庫的 Qt6 檢查
Section titled “官方外掛庫的 Qt6 檢查”上傳到 plugins.qgis.org 時會自動用 pyqgis4-checker 掃描,結果出現在版本頁的 Qt6 Check 分頁,列出要更新的檔案與行號。官方遷移說明寫的是「僅供參考、不會阻擋上傳與核准」;但 QGIS Hub Plugin 專案的遷移筆記記錄,它的 v0.7.0 曾因未全名化的列舉值(例如 Qgis.Success)被擋下。兩份文件說法不一致,最保險的做法是上傳前自己先跑過 pyqt5_to_pyqt6.py,把結果清乾淨。
新舊版本都要支援時的寫法
Section titled “新舊版本都要支援時的寫法”如果外掛還要支援很舊的 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 |
本單元目前沒有對應影片。
- 對自己的外掛資料夾搜尋
PyQt5、QRegExp、exec_(三個字串,列出出現位置。- 檢查方式:改完後三個字串在原始碼中都不再出現(註解除外)。
- 在備份上跑
pyqt5_to_pyqt6.py,用 Git diff 檢視修改。- 檢查方式:能逐一說明每處修改是哪一類(列舉值、import 位置、其他);有看不懂的修改就先不要提交。
- 在 QGIS 3.44 與 QGIS 4 各啟用一次外掛,執行每個功能。
- 檢查方式:兩邊的 記錄訊息 Log Messages 面板的 Python 錯誤分頁都沒有新錯誤。
- Migrate your plugin to QGIS 4(plugins.qgis.org):metadata 版本範圍規則、
supportsQt6已廢除、Qt6 Check 分頁 - Plugin migration to be compatible with Qt5 and Qt6(QGIS wiki):
pyqt5_to_pyqt6.py用法、列舉值對照 - QGIS Hub Plugin:Qt6 migration notes:一支真實外掛的遷移紀錄,含
QRegExp、測試、CI - pyqgis4-checker:含 Qt6 版 QGIS 與檢查腳本的 Docker 映像
- QGIS 4.0 Visual Changelog:發布日期與 Qt6 轉換說明