Czym jest PyQGIS? Automatyzacja QGIS w Pythonie

PyQGIS to sposób sterowania QGIS za pomocą kodu w Pythonie. Wszystko, co klikasz w QGIS, możesz zapisać jako kilka linijek Pythona: wczytać warstwę, uruchomić algorytm, zmienić styl, wyeksportować mapę. Dzięki temu to samo zadanie wykonasz na stu plikach bez stu serii kliknięć. PyQGIS jest w każdej instalacji QGIS, więc nie musisz niczego dodawać.

PyQGIS Developer Cookbook pisze, że narzędzia Pythona są „prawie identyczne” z tymi, w których zbudowano sam QGIS, więc możliwe jest niemal wszystko. Większość wtyczek QGIS, także nasze, powstaje właśnie z jego pomocą.

Kodu nie musisz już pisać samodzielnie. Szkic może przygotować czatbot, a agent potrafi w ogóle obejść się bez kodu: tworzymy takiego agenta, AI Agent, a niżej sprawdzam oba podejścia na tych samych sześciu zadaniach.

Gdzie uruchomić PyQGIS

Są cztery miejsca i każde pasuje do innego zadania.

W konsoli dostępny jest iface, obiekt sterujący oknem QGIS. Poza QGIS go nie ma, dlatego NameError: name 'iface' is not defined to jedno z najczęściej zadawanych pytań o PyQGIS na GIS Stack Exchange.

Skrypt przetwarzania zaczyna się od szablonu, który QGIS wypełnia za ciebie. Zmieniasz parametry wejściowe i te kilka linijek, które wykonują pracę, a skrypt pojawia się w panelu algorytmów jak wbudowane narzędzie.

Pierwszy skrypt PyQGIS

Otwórz konsolę Pythona, kliknij Pokaż edytor, zaznacz warstwę z budynkami w panelu „Warstwy” i wklej poniższy kod. Policzy on budynki każdego typu:

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())

Najwięcej pracy wykonują trzy obiekty: QgsProject.instance() to twój projekt, QgsVectorLayer i QgsRasterLayer to jego warstwy, a iface to okno programu. Dokumentacja API wymienia wszystkie klasy.

Uruchom dowolny algorytm QGIS z Pythona

Każdy algorytm z panelu „Algorytmy przetwarzania” można uruchomić jedną linijką Pythona, processing.run(), z tymi samymi ustawieniami co w jego oknie:

import processing

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

Nie musisz zgadywać nazw parametrów. Wypełnij okno algorytmu raz, a potem otwórz u dołu Zaawansowane > Kopiuj jako polecenie Pythona (Advanced > Copy as Python Command). QGIS poda dokładną linijkę do wklejenia w skrypcie.

Te same algorytmy działają bez uruchamiania QGIS, z terminala, poleceniem qgis_process run native:buffer. To droga dla zadania uruchamianego z harmonogramu na serwerze.

Co QGIS 4 zmienił w PyQGIS

QGIS 4.0, wydany 6 marca 2026, przeszedł na nowszą wersję Qt, biblioteki, na której opierają się okna i przyciski programu. Funkcje QGIS zmieniły się niewiele. Psuje się kod, który korzysta z Qt bezpośrednio, a większość problemów powodują trzy zmiany:

QGIS zawiera skrypt pyqt5_to_pyqt6.py, który przepisuje większość tych miejsc za ciebie, a resztę znajdzie pyqgis4-checker. Skrypty, które używają tylko algorytmów QGIS i processing.run(), zwykle działają bez zmian.

Czy ChatGPT lub Claude napiszą PyQGIS za ciebie?

W większości tak, jeśli opiszesz im swój projekt. Przetestowałem Claude Sonnet, czatbota podobnego do ChatGPT: jego skrypty uruchomiły się bez błędu we wszystkich sześciu zadaniach. Gdy opisałem warstwy, pola i ścieżki plików, wszystkie sześć wyników było poprawnych. Gdy podałem tylko nazwy warstw, jeden z sześciu był po cichu błędny: skrypt się uruchomił, nie wypisał nic niepokojącego i wypełnił 396 z 936 pikseli mapy wysokości fałszywą wysokością 0 m.

Wniosek jest prosty. Czatbot nie widzi twojego projektu, więc jakość jego kodu zależy od tego, jak dobrze go opiszesz, a błędny wynik może wyglądać dokładnie jak poprawny. Był też haczyk związany z QGIS 4: oba skrypty czatbota dla układu wydruku używały krótkich nazw Qt z tabeli powyżej i w QGIS 4 zatrzymałyby się w połowie.

Jak to zmierzyliśmy. 26 września 2026, w QGIS 3.44.7, na danych mapowych centrum Denpasar na Bali: sześć codziennych zadań, od liczenia budynków po eksport układu wydruku, po jednej próbie. Wynik uznawaliśmy za poprawny tylko wtedy, gdy przechodził osobny skrypt kontrolny, napisany przed uruchomieniami. Sześć zadań to mała próba.

Albo bez kodu: agent, który wykonuje kroki

Tworzymy AI Agent, więc ta sekcja dotyczy naszej własnej wtyczki. To panel czatu wewnątrz QGIS: wpisujesz zadanie, a agent czyta twój projekt, uruchamia algorytmy i sprawdza wynik. Nie ma kodu do wklejania ani projektu do opisywania.

Dałem mu te same sześć zdań z zadaniami, bez opisu projektu. Wszystkie sześć wykonał poprawnie, w czasie od 6,4 do 42,8 s na zadanie i 148,8 s łącznie. Dwa razy zatrzymał się z pytaniem przed zapisem pliku i kliknąłem Zezwól. W zadaniu z wysokościami, na którym potknął się czatbot, agent najpierw odczytał warstwę i poprawnie ustawił puste piksele.

Darmowa droga nadal jest dobra: konsola, Kopiuj jako polecenie Pythona i czatbot zaprowadzą cię daleko, o ile sprawdzasz wynik. Jeśli wolisz opisać zadanie i dostać gotową warstwę, agent wykona kroki za ciebie.

Wypróbuj AI Agent w QGIS za darmo, bez karty

Gdzie ludzie utykają

Policzyliśmy pytania pod tutorialami QGIS na YouTube: w 1692 tutorialach z komentarzami 391 komentarzy w 245 tutorialach prosi o pomoc w Pythonie lub automatyzacji. Wracają te same trzy problemy:

• Nie znaleziono warstwy. mapLayersByName("roads") nic nie znajdzie, jeśli nazwa różni się jedną literą lub spacją.
• Odległości w stopniach. Bufor 50 m na warstwie w EPSG:4326 to bufor 50 stopni, bo ten układ liczy w stopniach. Najpierw przelicz warstwę do innego układu, jak opisujemy w tekście czym jest układ współrzędnych (CRS).
• iface poza QGIS. Skrypty uruchamiane poza oknem nie mają iface. Użyj QgsProject i processing.run().

Co warto zapamiętać

PyQGIS to interfejs Pythona do QGIS. Działa w konsoli Pythona, w skryptach przetwarzania, we wtyczkach oraz poza QGIS dzięki qgis_process.

processing.run() uruchamia dowolny algorytm QGIS z kodu, a Kopiuj jako polecenie Pythona daje dokładną linijkę z okna algorytmu.

QGIS 4 zmienił niektóre nazwy Qt, na przykład Qt.AlignLeft. Kod, który buduje własne okna, może wymagać drobnych poprawek.

W naszym teście sześciu zadań kod czatbota zawsze się uruchamiał, ale raz dał błędny wynik, gdy projekt nie był opisany. Agent wewnątrz QGIS, taki jak AI Agent, wykonał wszystkie sześć poprawnie na podstawie samego zdania z zadaniem.

Najczęstsze pytania

Do czego służy PyQGIS?

Do automatyzacji QGIS w Pythonie: wczytywania i edycji warstw, uruchamiania algorytmów na wielu plikach, stylizacji map, budowania układów wydruku oraz pisania wtyczek i skryptów, z których mogą korzystać inni. Działa też poza oknem QGIS, w zadaniach na serwerze.

Czy PyQGIS to to samo co Python?

PyQGIS to zestaw narzędzi QGIS, których używasz z poziomu Pythona. Piszesz zwykły Python, a PyQGIS dodaje takie elementy jak QgsVectorLayer i processing.run(). Jest dostarczany z QGIS i korzysta z Pythona zainstalowanego razem z programem.

Jak otworzyć konsolę Pythona w QGIS?

Wtyczki > Konsola Pythona (Plugins > Python Console) lub Ctrl+Alt+P. Kliknij Pokaż edytor, aby pisać dłuższe skrypty, zapisywać je jako pliki .py i uruchamiać zieloną strzałką.

Czy moje skrypty PyQGIS nadal działają w QGIS 4?

Skrypty, które używają tylko algorytmów QGIS i processing.run(), zwykle tak. Skrypty budujące własne okna często wymagają drobnych zmian, na przykład Qt.AlignmentFlag.AlignLeft zamiast Qt.AlignLeft. Oficjalny skrypt pyqt5_to_pyqt6.py poprawia większość takich miejsc.

Czy mogę zautomatyzować QGIS bez Pythona?

Tak. Graphical Modeler łączy algorytmy wizualnie, a przetwarzanie wsadowe uruchamia jeden algorytm na wielu plikach. Wtyczka z agentem AI idzie dalej: wpisujesz zadanie zwykłymi słowami, a ona uruchamia algorytmy w twoim projekcie. Nasza, AI Agent, ma plan Free.

Na dalszą drogę: czym jest agent AI w QGIS wyjaśnia, jak działają agenci i którego wybrać, a AI Agent możesz wypróbować za darmo. Czym jest układ współrzędnych (CRS) omawia przeliczanie układu, od którego zaczyna większość skryptów, a czym jest QGIS MCP pokazuje drogę dla użytkowników Claude Code i Cursora.