Every QGIS user reaches the same fork. Down one path, the dialog path, every task is a sequence of clicks that evaporates when it is done, unrepeatable and unauditable. Down the other, the same tasks are lines of code: saved, rerun, adapted, and shared. The door between the paths is a panel most users have never opened: Plugins, Python Console, shortcut Ctrl+Alt+P. The console is not a toy for programmers visiting GIS. It is the application's second interface, a live Python session wired into the running QGIS, where the map canvas, the loaded layers, and the entire Processing toolbox answer to typed commands. This guide teaches the console as a working tool: what is preloaded, what to type first, and the ladder from a one-line experiment to a scripted workflow.
Home / GIS and Open Map Data for Beginners
The QGIS Python Console: Drive the Whole Application With Code

Photo: Lukas Blazek / Pexels
Drive QGIS With Code: The Console Checklist
Check off each step as you finish it. Your progress stays on this page.
0 of 7 complete
0% done
The Session: What Is Already There
Open the console and QGIS hands you a Python prompt with the crucial object preloaded: iface, the interface object, your handle on the running application. Through it, the live session is reachable: iface.mapCanvas() is the canvas on your screen, iface.activeLayer() is the layer you have selected, and changes you make through code appear in the application immediately, because it is the same application, not a simulation of one.
The second handle is the project: QgsProject.instance() returns the current project, the registry of layers. From it, mapLayers() lists what is loaded and mapLayersByName('roads') fetches a layer by name, the two calls that begin nearly every working script. The first five minutes in the console should be spent on exactly this reconnaissance: print the layer list, fetch a layer, ask it its feature count, its CRS, its fields. You are learning the application's own answers about your data, and the habit, ask the project, never assume, is the console's first discipline.
The Editor: Where Console Work Grows Up
The console panel includes a built-in editor, and the division of labor between the prompt and the editor is the workflow's spine. The prompt is for experiments: one line, immediate answer, cheap failure. The editor is for anything you would grieve losing: multi-line scripts, loops over layers, the algorithm runs with their parameters spelled out. Write in the editor, run into the same live session, and save the file with the project, because a QGIS workflow that lives only in a scrolled-away console transcript is a dialog workflow wearing a costume. The saved script is the deliverable: next month's rerun, next year's audit, the colleague's starting point.
processing.run: The Whole Toolbox, Addressable
The console's superpower has a name: processing.run. Every algorithm in the Processing toolbox, native, GDAL, GRASS, SAGA, every tool this site's guides teach through dialogs, is callable by its algorithm ID with a parameter dictionary:
```python
result = processing.run("native:dissolve", {
'INPUT': 'parcels',
'FIELD': ['district'],
'OUTPUT': 'memory:districts'
})
```
That call is the dissolve from the merge polygons guide, with the dialog replaced by text. The consequences compound: a morning's pipeline, clip, dissolve, zonal statistics, export, becomes a twenty-line script that runs identically on next quarter's data; parameters stop being memories of clicks and become arguments you can read; and the algorithm IDs and parameter names, discoverable through processing.algorithmHelp and the toolbox's own history, turn the entire Processing library into an API. Batch work stops being a personality trait and becomes a loop: for each file in a folder, for each layer in a project, for each district in a list, run the chain. This is the moment QGIS changes from a place you work into a machine you operate.

startup.py: Code That Runs Before You Do
The console's deepest hook is a file: startup.py in your QGIS user profile folder. QGIS executes it at launch, which makes it the home for your standing setup: importing the libraries every session needs, defining the helper functions your team shares, registering custom actions, even loading the layers every project in your practice starts from. Used with restraint, it turns each launch into a prepared bench. Used greedily, it becomes a haunted house of side effects nobody remembers installing, so the discipline is: startup.py holds declarations and definitions, never jobs. The script that processes data runs when you run it, in the open, with its output where you can see it.
The Ladder: From One Line to a Practice
Console skill compounds in a predictable order, and naming the rungs helps you climb deliberately:
- Reconnaissance: read the project, the layers, the counts, the CRSs. No changes, only questions.
- Selection and expression: drive selections and field calculations through code, the dialog work of the expression builder made repeatable.
- Algorithm runs: single processing.run calls replacing single dialogs, the dissolve above.
- Chains and loops: the pipeline as a script, the folder as a loop, outputs named by rule.
- Products: scripts that open a project, run the chain, and lay out the map, the analysis as a command.
Notice what the ladder never requires: building plugins, packaging, distribution. That is a further country, entered through the same door when a script deserves a button. The console serves the whole ladder below it, which is where most working analysts actually live, and the plugins guide covers the neighboring skill of managing the installed tools the console can also drive.
A First Real Script: The Layer Census
Abstract ladders persuade nobody; a working script does. Here is the census, the small report every project deserves and no dialog produces: for each layer in the project, its name, its feature count, and its CRS, printed as a table you can paste into a project record.
```python
project = QgsProject.instance()
for layer in project.mapLayers().values():
if layer.type() == QgsMapLayer.VectorLayer:
crs = layer.crs().authid()
print(layer.name(), layer.featureCount(), crs)
```
Five lines, and each one teaches a load-bearing idea. The project is asked, not assumed. Layers are filtered by type before they are questioned, because raster layers do not answer vector questions. The CRS is printed as its authority code, EPSG:4326 and its kin, the form in which CRSs should travel between people. Run it on any project you inherit and you know more in four seconds than an hour of clicking layer properties would tell you: which layers are empty, which are in the wrong CRS (the census exposes the degrees layer hiding among the meters, the root of half the wrong answers in GIS), and which are named like their contents or like their author's mood. Extend it as your practice demands: add geometry types, field counts, the layers whose names contain a year. The census is a genre, not a script: the project's vital signs, taken by code, on demand, identically every time. Teams that adopt it stop arguing about what is in a project, because the project answers for itself.
Errors Are Tuition, Collected Cheaply
Console work fails in the open, and the failures are instructive in a way dialog failures never are. A misspelled layer name returns an empty list and a script that does nothing, loudly, in a way you can inspect. A wrong parameter name in processing.run raises an error that names the parameter it expected, which is the documentation arriving exactly when it is needed. The habit that converts these moments into skill is reading the traceback's last line first, it states the failure in plain terms, and treating the console's transcript as a lab notebook: what was tried, what the application answered, what the answer taught. Dialog users repeat their mistakes because the dialog forgets them. Console users accumulate a written record of theirs, and the record is why the ladder in this guide is climbed faster than it looks.
Console Manners: Working Safely in a Live Application
The console's power is unmediated: code runs against your open project, and a careless line edits real layers. Three manners keep the power safe. Work on copies at decision points: send algorithm outputs to memory layers or new files, never overwrite an input you cannot recreate. Print before you mutate: the reconnaissance habit again; a script that reports what it found before it changes anything fails politely instead of silently. Save scripts with the data they belong to: a script in the project folder, named for its job, is documentation; a script in a downloads folder is litter. None of this is ceremony. It is the difference between a scripted practice and a faster way to make unrepeatable mistakes.
Related Guides
If this page answered part of the question, these GIS and open data guides cover the rest of the same ground:
- Kriging in QGIS: Interpolation With a Semivariogram, and When IDW Is Enough: One of the provider workflows the console makes repeatable.
- LiDAR in QGIS: Native Point Clouds From LAS to 3D: Point cloud processing chains are console work par excellence: long, parameterized, and rerun often.
- Rule-Based Symbology in QGIS: Styles Written as Conditions: Styles are objects too: the console can build and apply them like any other.
- How to Use QGIS Plugins: Install, Manage, and the Beginner Set Worth Having: The neighboring door: installing tools, where this guide drives the application itself.
Frequently Asked Questions
How do I open the Python Console in QGIS?
Through Plugins, Python Console, or the keyboard shortcut Ctrl+Alt+P. The console opens as a panel with a live Python prompt wired into the running application, with the iface object preloaded.
What is iface in the QGIS console?
The preloaded interface object: your handle on the running application. iface.mapCanvas() returns the live canvas, iface.activeLayer() the selected layer, and changes made through iface and the project API appear in QGIS immediately, because the console session is the application itself.
How do I run a Processing algorithm from the console?
With processing.run, passing the algorithm ID and a parameter dictionary: processing.run("native:dissolve", {...}). Every toolbox algorithm, native, GDAL, GRASS, and SAGA, is callable this way, and processing.algorithmHelp documents each one's parameters.
What is startup.py in QGIS?
A Python file in your QGIS user profile folder that QGIS executes at every launch. It is the place for standing setup: imports, shared helper functions, and definitions your sessions rely on. Keep jobs out of it; startup.py prepares the bench, it does not run the work.
Is the console only for programmers?
No. Its first rung is reconnaissance, printing what the project contains, which any QGIS user benefits from, and its editor turns multi-step dialog routines into saved, rerunnable scripts one algorithm at a time. The ladder from single commands to scripted chains is climbed gradually, inside ordinary project work.
Photo credits: Lukas Blazek (Pexels); Luis Gomes (Pexels). Photos are served from this site; follow the credit to the library page for the original.