跳至內容
QGIS
教學

PyQGIS 是什麼?用 Python 自動化 QGIS 教學

發布於 更新於

PyQGIS 是用 Python 程式碼控制 QGIS 的方式。凡是您能在 QGIS 裡點選完成的事,都能寫成幾行 Python:載入圖層、執行工具、更改樣式、匯出地圖。這讓您不必點一百次,就能對一百個檔案重複同一項作業。每個 QGIS 安裝都內建 PyQGIS,不需要另外安裝任何東西。

QGIS 在峇里島登巴薩市中心的地圖下方開啟 Python 主控台。右側編輯器裡是名為 school_zones.py 的腳本,內容是重新投影學校、在學校周圍畫出 100 公尺環域,再選取環域內的建物。左側輸出顯示 864 of 7015 buildings are within 100 m of a school,接著是 yes 818、school 19、commercial 15、college 5。地圖上學校環域是藍色圓圈,被選取的建物是橘色。
QGIS 裡的 Python 主控台。這支腳本找出距離學校 100 m 以內的建物:登巴薩市中心 7,015 個建物中有 864 個。

PyQGIS Developer Cookbook 指出,這些 Python 工具與打造 QGIS 本身的工具「幾乎相同」,所以幾乎什麼事都做得到。大多數 QGIS 外掛,包括我們的外掛,都是用它寫成的。

現在您不一定要自己寫程式。聊天機器人可以幫您起草,AI 代理甚至可以完全跳過程式碼:我們開發了一個,叫 AI Agent,後文我會讓兩者做同樣的六項任務來比較。

在哪裡執行 PyQGIS

有四個地方,各自適合不同的工作。

位置開啟方式適合用來
Python 主控台「外掛程式」→「Python 主控台」(Ctrl+Alt+P)對目前開啟的專案做快速修正
空間運算指令稿「空間運算」→「工具箱」→「指令稿」→「從範本建立新腳本」可重複使用、有自己輸入項目的工具,與工具箱裡其他工具一樣
外掛QGIS 設定檔裡的一個資料夾有自己按鈕、可分享給他人的工具
獨立腳本純 Python,或 qgis_process 指令不開 QGIS 視窗也能執行的工作,例如在伺服器上

主控台提供 iface,這是控制 QGIS 視窗的物件。在 QGIS 之外它不存在,所以 NameError: name 'iface' is not defined 是 GIS Stack Exchange 上最常見的 PyQGIS 問題之一。

空間運算指令稿從 QGIS 替您填好的範本開始。您只要修改輸入項目和真正做事的幾行程式,這支腳本就會像內建工具一樣出現在工具箱裡。

QGIS 空間運算指令稿編輯器顯示範本開頭:一個名為 ExampleProcessingAlgorithm 的類別,註解說明它接收一個向量圖層並建立一個相同的圖層,另有常數 INPUT 與 OUTPUT,以及一個回傳 myscript 的 name 方法。
「從範本建立新腳本」會開啟一個可直接修改的運作範例。

第一支 PyQGIS 腳本

開啟 Python 主控台,按下「顯示編輯器」,在圖層面板選取一個建物圖層,貼上下面的程式。它會計算每種建物類型的數量:

from collections import Counter

layer = iface.activeLayer()  # the layer selected in the Layers panel
counts = Counter(f["building"] for f in layer.getFeatures())

for kind, n in counts.most_common(5):
    print(kind, n)
print("Total:", layer.featureCount(), "features in", layer.crs().authid())

主要有三個物件:QgsProject.instance() 是您的專案,QgsVectorLayer 與 QgsRasterLayer 是專案裡的圖層,iface 是視窗。API 參考文件列出了每一個類別。

用 Python 執行任何 QGIS 工具

空間運算工具箱裡的每個工具,都能用 processing.run() 這一行 Python 執行,設定項目與工具視窗相同:

import processing

result = processing.run("native:buffer", {
    "INPUT": "buildings.gpkg",
    "DISTANCE": 50,
    "OUTPUT": "buffered.gpkg",
})

您不需要猜設定項目的名稱。先在工具視窗填好一次,再開啟底部的「進階」→「複製為 Python 指令」,QGIS 就會給您可直接貼進腳本的那一行。

QGIS「計算多邊形內的點數」工具視窗,多邊形是 kelurahan,點是 schools。底部的「進階」選單已展開,「複製為 Python 指令」被標示出來,下方依序是「複製為 qgis_process 指令」、「複製為 JSON」與「貼上設定」。
「複製為 Python 指令」可把您手動設定好的任何工具變成一行程式碼。

空間連接的做法相同,用 native:joinattributesbylocation。我們的空間連接指南在 103,910 棟建物上量測了它的耗時。

同樣的工具不開 QGIS 也能執行,在終端機輸入 qgis_process run native:buffer 即可。排程在伺服器上的作業就是走這條路。

QGIS 4 對 PyQGIS 改了什麼

2026 年 3 月 6 日發布的 QGIS 4.0,改用較新版本的 Qt,也就是 QGIS 視窗和按鈕背後的工具套件。QGIS 本身的函式幾乎沒變,會出問題的是直接使用 Qt 的程式碼,而三項改動就造成大部分的狀況:

QGIS 3QGIS 4
簡短名稱,例如 Qt.AlignLeft完整名稱,例如 Qt.AlignmentFlag.AlignLeft
QRegExpQRegularExpression
對話框的 exec_()exec()

QGIS 附有一支腳本 pyqt5_to_pyqt6.py,能替您改寫大部分項目,其餘的可以用 pyqgis4-checker 找出來。只使用 QGIS 工具和 processing.run() 的腳本,通常不用修改就能執行。

ChatGPT 或 Claude 能幫您寫 PyQGIS 嗎?

大致上可以,前提是您要告訴它專案的內容。我測試了 Claude Sonnet,它是和 ChatGPT 類似的聊天機器人,它寫的腳本在六項任務中全都沒有報錯。當我描述圖層、欄位和檔案路徑時,六個結果全部正確。當我只給圖層名稱時,六個裡有一個悄悄出錯:腳本照常執行,沒有任何異常輸出,卻把高程地圖 936 個像素中的 396 個填成了不存在的 0 m 高度。

執行時沒有錯誤結果正確
聊天機器人,提示中描述專案6/66/6
聊天機器人,只給圖層名稱6/65/6
QGIS 內的 AI 代理,只給一句任務6/66/6

結論很簡單。聊天機器人看不到您的專案,所以程式碼的品質取決於您描述得多清楚,而錯誤的結果看起來可能和正確的一模一樣。另外還有一個 QGIS 4 的問題:聊天機器人的兩支列印圖面配置腳本都用了上表的簡短 Qt 名稱,在 QGIS 4 上會執行到一半就停下。

我們怎麼測的。 2026 年 9 月 26 日,在 QGIS 3.44.7 中,使用峇里島登巴薩市中心的地圖資料:六項日常任務,從計算建物數量到匯出列印圖面配置,每項只試一次。只有事先寫好的另一支檢查腳本通過,結果才算正確。六項任務的樣本很小。

或者跳過程式碼:讓代理替您執行步驟

我們開發了 AI Agent,所以這一節談的是我們自己的外掛。它是 QGIS 裡的對話面板:您輸入任務,它讀取您的專案、執行工具並檢查結果。不用貼程式碼,也不用描述專案。

我給它同樣的六句任務,沒有描述專案。六項全部答對,每項耗時 6.4 到 42.8 秒,六項合計 148.8 秒。它有兩次在寫入檔案前停下來詢問,我按了允許。在讓聊天機器人出錯的那項高程任務上,它先讀取圖層,正確設定了空白像素。

QGIS 右側是 AI Agent 面板。請求內容是依 building 欄位為建物圖層設定樣式:commercial 紅色、school 藍色、hotel 綠色、house 紫色,其他值淺灰色。AI Agent 回覆已設定好建物樣式,並檢查了每個類別。登巴薩的地圖上,灰色建物之間有紅色的商業建物、綠色的旅館和紫色的住宅,圖層面板列出這五個類別。
一句話,建物就依類型設定好樣式。不必閱讀或貼上任何程式碼。

免費的路線仍然很好:主控台、「複製為 Python 指令」和聊天機器人能帶您走很遠,只要記得檢查結果。如果您寧可描述任務就拿到圖層,AI Agent 會替您完成這些步驟。

大家卡在哪裡

我們統計了 YouTube 上 QGIS 教學影片底下的留言:在 1,692 支有留言的教學影片中,245 支影片共有 391 則留言在求助 Python 或自動化的問題。同樣的三個問題一再出現:

  • 找不到圖層。 名稱只要差一個字母或一個空格,mapLayersByName("roads") 就找不到任何東西。
  • 距離變成度數。 對 EPSG:4326 的圖層做 50 m 環域,實際上是 50 度的環域,因為這個坐標系統以度為單位。請先重新投影,做法見什麼是坐標參考系統。
  • 在 QGIS 之外使用 iface。 在視窗之外執行的腳本沒有 iface,請改用 QgsProject 和 processing.run()。

重點整理

PyQGIS 是 QGIS 的 Python 介面。它可以在 Python 主控台、空間運算指令稿、外掛中執行,也能用 qgis_process 在 QGIS 之外執行。

processing.run() 能用程式碼執行任何 QGIS 工具,而「複製為 Python 指令」會把工具視窗的設定變成可直接使用的那一行。

QGIS 4 更改了一些 Qt 名稱,例如 Qt.AlignLeft。自己建立視窗的程式碼可能需要小幅修改。

在我們的六項任務測試中,聊天機器人的程式碼都能執行,但在沒有描述專案時錯了一次。QGIS 內的 AI 代理,例如 AI Agent,只憑一句任務就六項全對。

常見問題

想進一步了解,QGIS 中的 AI 代理是什麼說明代理如何運作以及該如何選擇,AI Agent 則是我們的外掛,可以免費試用。什麼是坐標參考系統介紹大多數腳本一開始就需要的重新投影,什麼是 QGIS MCP 則為使用 Claude Code 與 Cursor 的人說明另一條路。

在 QGIS 裡開口就能完成

AI Agent 會在你自己的 QGIS 專案中,執行你描述的任務。免費使用,不需信用卡。

免費試用 AI Agent
由以下作者撰寫Yvann Barbot
·3 min read

繼續閱讀