What Is PyQGIS? Automate QGIS With or Without Code

PyQGIS is the way to control QGIS with Python code. Anything you can click in QGIS, you can also write as a few lines of Python: load a layer, run a tool, change a style, export a map. That lets you repeat the same job on a hundred files without clicking a hundred times. It comes with every QGIS install, so there is nothing to add.

The PyQGIS Developer Cookbook says the Python tools are "nearly identical" to the ones QGIS itself is built with, so almost anything is possible. Most QGIS plugins, ours included, are written with it.

You don't have to write the code yourself anymore. A chatbot can draft it, and an agent can skip the code entirely: we build one, AI Agent, and further down I test both against the same six tasks.

Where you can run PyQGIS

There are four places, and each one suits a different job.

The console gives you iface, the object that controls the QGIS window. Outside QGIS it doesn't exist, which is why NameError: name 'iface' is not defined is one of the most asked PyQGIS questions on GIS Stack Exchange.

A Processing script starts from a template that QGIS fills in for you. You change the inputs and the few lines that do the work, and the script shows up in the toolbox like a built-in tool.

Your first PyQGIS script

Open the Python console, click Show Editor, select a buildings layer in the Layers panel, and paste this. It counts the buildings of each type:

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

Three objects do most of the work: QgsProject.instance() is your project, QgsVectorLayer and QgsRasterLayer are its layers, and iface is the window. The API reference lists every class.

Run any QGIS tool from Python

Every tool in the Processing Toolbox can run from one line of Python, processing.run(), with the same settings as its window:

import processing

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

You don't need to guess the setting names. Fill in the tool's window once, then open Advanced > Copy as Python Command at the bottom. QGIS gives you the exact line to paste into your script.

The same tools run without opening QGIS, from a terminal, with qgis_process run native:buffer. That's the route for a scheduled job on a server.

What QGIS 4 changed for PyQGIS

QGIS 4.0, released on 6 March 2026, moved to a newer version of Qt, the toolkit behind its windows and buttons. The QGIS functions stayed almost the same. What breaks is code that touches Qt directly, and three changes cause most of it:

QGIS ships a script, pyqt5_to_pyqt6.py, that rewrites most of these for you, and the pyqgis4-checker finds the rest. Scripts that only use QGIS tools and processing.run() usually work unchanged.

Can ChatGPT or Claude write PyQGIS for you?

Mostly yes, if you tell it about your project. I tested Claude Sonnet, a chatbot like ChatGPT, and its scripts ran without an error in all six tasks. When I described the layers, fields and file paths, all six results were right. When I gave only the layer names, one of the six was silently wrong: the script ran, printed nothing alarming, and filled 396 of 936 pixels of an elevation map with a fake height of 0 m.

The lesson is simple. A chatbot can't see your project, so the quality of its code depends on how well you describe it, and a wrong result can look exactly like a right one. There was also a QGIS 4 catch: both of the chatbot's print-layout scripts used the short Qt names from the table above, and they would stop halfway on QGIS 4.

How we measured this. On 26 September 2026, in QGIS 3.44.7, with map data for central Denpasar, Bali: six everyday tasks, from counting buildings to exporting a print layout, one attempt each. A result counted as correct only if a separate check script, written before the runs, passed. Six tasks is a small sample.

Or skip the code: an agent that runs the steps

We build AI Agent, so this section is about our own plugin. It's a chat panel inside QGIS: you type the task, and it reads your project, runs the tools and checks the result. There's no code to paste and no project to describe.

I gave it the same six task sentences, with no description of the project. It got all six right, taking between 6.4 and 42.8 seconds per task, and 148.8 seconds for all six. It stopped twice to ask before writing a file, and I clicked Allow. On the elevation task that tripped the chatbot, it read the layer first and set the empty pixels correctly.

The free route stays a good one: the console, Copy as Python Command and a chatbot will take you far, as long as you check the result. If you'd rather describe the task and get the layer, the agent does the steps for you.

Try AI Agent free in QGIS, no card needed

Where people get stuck

We counted the questions under QGIS tutorials on YouTube: in 1,692 tutorials with comments, 391 comments across 245 tutorials ask for help with Python or automation. The same three problems come back:

• Layer not found. mapLayersByName("roads") finds nothing if the name differs by one letter or a space.
• Distances in degrees. A 50 m buffer on a layer in EPSG:4326 is a 50-degree buffer, because that system counts in degrees. Reproject first, as explained in what a CRS is.
• iface outside QGIS. Scripts run outside the window have no iface. Use QgsProject and processing.run() instead.

What to remember

PyQGIS is the Python interface to QGIS. It runs in the Python console, in Processing scripts, in plugins, and outside QGIS with qgis_process.

processing.run() runs any QGIS tool from code, and Copy as Python Command gives you the exact line from a tool's window.

QGIS 4 renamed some Qt names, such as Qt.AlignLeft. Code that builds its own windows may need small fixes.

In our six-task test, chatbot code always ran but was wrong once when the project wasn't described. An agent inside QGIS, such as AI Agent, got all six right from the task sentence alone.

Questions people ask

What is PyQGIS used for?

Automating QGIS with Python: loading and editing layers, running tools on many files, styling maps, building print layouts, and writing plugins or scripts others can reuse. It also runs outside the QGIS window for jobs on a server.

Is PyQGIS the same as Python?

PyQGIS is a set of QGIS tools you use from Python. You write normal Python, and PyQGIS adds things like QgsVectorLayer and processing.run(). It comes with QGIS and uses the Python that QGIS installs.

How do I open the Python console in QGIS?

Plugins > Python Console, or Ctrl+Alt+P. Click Show Editor to write longer scripts, save them as .py files, and run them with the green arrow.

Do my PyQGIS scripts still work in QGIS 4?

Scripts that only use QGIS tools and processing.run() usually do. Scripts that build their own windows often need small changes, such as Qt.AlignmentFlag.AlignLeft instead of Qt.AlignLeft. The official pyqt5_to_pyqt6.py script fixes most of them.

Can I automate QGIS without Python?

Yes. The Graphical Modeler chains tools visually, and batch mode runs one tool on many files. An AI agent plugin goes further: you type the task in plain words and it runs the tools in your project. Ours, AI Agent, has a free plan.

To go further, what an AI agent in QGIS is explains how agents work and which to pick, and AI Agent is ours to try free. What a CRS is covers the reprojection most scripts need first, and what QGIS MCP is shows the route for Claude Code and Cursor users.