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

Q: PyQGIS 和 Python 一樣嗎？

PyQGIS 是一組讓您從 Python 使用的 QGIS 工具。您寫的是一般的 Python，PyQGIS 則加上 QgsVectorLayer 和 processing.run() 這類功能。它隨 QGIS 一起安裝，使用 QGIS 安裝的那一套 Python。

Q: QGIS 的 Python 主控台要怎麼開啟？

依序點選「外掛程式」→「Python 主控台」，或按 Ctrl+Alt+P。按下「顯示編輯器」就能撰寫較長的腳本、存成 .py 檔案，並用綠色箭頭執行。

Q: 我的 PyQGIS 腳本在 QGIS 4 還能用嗎？

只使用 QGIS 工具和 processing.run() 的腳本通常可以。自己建立視窗的腳本往往需要小幅修改，例如用 Qt.AlignmentFlag.AlignLeft 取代 Qt.AlignLeft。官方的 pyqt5_to_pyqt6.py 腳本能修正大部分項目。

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 指令」可把您手動設定好的任何工具變成一行程式碼。

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

QGIS 4 對 PyQGIS 改了什麼

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

QGIS 3	QGIS 4
簡短名稱，例如 `Qt.AlignLeft`	完整名稱，例如 `Qt.AlignmentFlag.AlignLeft`
`QRegExp`	`QRegularExpression`
對話框的 `exec_()`	`exec()`

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

ChatGPT 或 Claude 能幫您寫 PyQGIS 嗎？

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

	執行時沒有錯誤	結果正確
聊天機器人，提示中描述專案	6／6	6／6
聊天機器人，只給圖層名稱	6／6	5／6
QGIS 內的 AI 代理，只給一句任務	6／6	6／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 會替您完成這些步驟。

免費試用 QGIS 的 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，只憑一句任務就六項全對。

常見問題

PyQGIS 可以用來做什麼？

用 Python 自動化 QGIS：載入與編輯圖層、對大量檔案執行工具、設定地圖樣式、建立列印圖面配置，以及撰寫可供他人重複使用的外掛或腳本。它也能在 QGIS 視窗之外執行，處理伺服器上的作業。

PyQGIS 和 Python 一樣嗎？

PyQGIS 是一組讓您從 Python 使用的 QGIS 工具。您寫的是一般的 Python，PyQGIS 則加上 QgsVectorLayer 和 processing.run() 這類功能。它隨 QGIS 一起安裝，使用 QGIS 安裝的那一套 Python。

QGIS 的 Python 主控台要怎麼開啟？

依序點選「外掛程式」→「Python 主控台」，或按 Ctrl+Alt+P。按下「顯示編輯器」就能撰寫較長的腳本、存成 .py 檔案，並用綠色箭頭執行。

我的 PyQGIS 腳本在 QGIS 4 還能用嗎？

只使用 QGIS 工具和 processing.run() 的腳本通常可以。自己建立視窗的腳本往往需要小幅修改，例如用 Qt.AlignmentFlag.AlignLeft 取代 Qt.AlignLeft。官方的 pyqt5_to_pyqt6.py 腳本能修正大部分項目。

不用 Python 也能自動化 QGIS 嗎？

可以。圖形化模型設計器能用視覺方式串接工具，批次模式則可對多個檔案執行同一個工具。AI 代理外掛更進一步：您用日常語言輸入任務，它就在您的專案裡執行工具。我們的 AI Agent 有免費方案。

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