QGIS & PyQGIS
Driving QGIS from Python: Processing algorithms, layouts, plugins and headless runs.
QGIS is a very large library of tested spatial algorithms that happens to ship with a user interface. Driving it from Python means using the same Processing framework the interface uses — there is no separate scripting API, which is why the History panel records the exact call the dialog made, and why a script and a manual run cannot silently diverge.
The difficulty is almost never the algorithms. It is the environment: which Python has the bindings, what the prefix path has to be, initialising Processing separately from the application, keeping a reference to a layer so C++ does not collect it mid-run, and exiting cleanly so a scheduled job actually finishes. None of those produce a Python traceback when they go wrong.
Below: the concepts cover the object model and the extension points; the how-to guides run algorithms, build models, style layers and export layouts; and the fixes are the import errors, the missing algorithms and the segmentation faults.
🧭 Start with the concepts
The ideas the how-to guides below assume you already have.
- How to Automate QGIS with Python (PyQGIS): The Complete Workflow
- PyQGIS vs GeoPandas: Which to Use for GIS Automation
- The QGIS Processing Framework Explained
- QGIS Data Providers Explained: How QGIS Reads Any Data Source
- The PyQGIS API Map: Which Class Does What
- How QGIS Styling Works: Renderers, Symbols and Rules
Show every concept in this topic
⚙️ Then do the task
Step-by-step walkthroughs with code you can copy and adapt.
- How to Run QGIS Processing Algorithms from Python
- How to Run a PyQGIS Script Headless Without Opening QGIS
- How to Batch Process Layers in QGIS with PyQGIS
- How to Build a QGIS Processing Model and Run It from Python
- How to Write a Custom QGIS Processing Script Algorithm in Python
- How to Style Layers and Export Map Layouts from PyQGIS
Show every how-to guide in this topic
- How to Move Data Between QGIS and GeoPandas
- How to Run Field Calculator Expressions from PyQGIS
- How to Add, Edit and Delete Features with PyQGIS
- How to Build and Save a QGIS Project File from Python
- How to Load and Write PostGIS Layers from PyQGIS
- How to Automate QGIS from the Command Line with qgis_process
🔧 When it breaks
The errors this topic produces, with the cause explained rather than just the command.
- How to Fix "ModuleNotFoundError: No module named 'qgis'"
- PyQGIS Script Crashes with a Segmentation Fault: How to Fix It
- QGIS Processing "Algorithm Not Found" Error in Python: How to Fix It
- PyQGIS Layer Fails to Load (isValid() Returns False): How to Fix It
- qt.qpa.plugin: Could Not Load the Qt Platform Plugin xcb in PyQGIS
- PyQGIS Processing Output Is Empty: How to Fix It
Learning paths through this topic
A curated route rather than a list — the guides in the order that builds on itself.
Related topics
Subjects that keep coming up alongside this one, most overlap first.