qgis-process

Project URL: https://github.com/qgis/QGIS

Documentation URL: https://github.com/qgis/QGIS-Documentation

Online documentation: https://docs.qgis.org/3.40/en/docs/user_manual/processing/standalone.html

License: GNU General Public License v2.0+

Overview

qgis_process is a command-line tool bundled with QGIS (QGIS Processing Executor), allowingwithout launching the QGIS desktop application, Processing algorithms and models (built-in algorithms or those provided by plugins) to be run directly from the command line. It is suitable for server-side batch processing, CI/CD automation pipelines, scripted GIS workflows, and similar scenarios.

Source code location:src/process/ in the directory main.cpp、qgsprocess.cpp、qgsprocess.h。

Environment preparation

Prerequisites

Install QGIS 3.16+ (qgis_process available since QGIS 3.16)
Ensure qgis_process executable is in PATH Medium

Headless server (no window system)

Before running on a system without a window manager, set the environment variable:

export QT_QPA_PLATFORM=offscreen

Verify installation

qgis_process --version

Command-line syntax

qgis_process [--help] [--version] [--json] [--verbose] [--no-python] [--skip-loading-plugins] [command] [algorithm id | model path | script path] [parameters]

Global options

Option	Description
`--help` or `-h`	Output help information
`--version` or `-v`	Output all version information related to QGIS Process
`--json`	Output results in JSON format (AI/script friendly)
`--verbose`	Output verbose logs
`--no-python`	Disable Python support (faster startup)
`--skip-loading-plugins`	Skip loading enabled plugins (faster startup)

Available commands

Command	Description
`plugins`	List available and activated plugins
`plugins enable <name>`	Enable an installed plugin
`plugins disable <name>`	Disable an installed plugin
`list`	List all available Processing algorithms
`help <algorithm_id>`	Show help information for a specified algorithm
`run <algorithm_id> [-- PARAM=VALUE ...]`	Run a specified algorithm

Note: Only installed plugins that declare metadata.txt in hasProcessingProvider=yes can be recognized and loaded by qgis_process Identify and load.

Core usage

1. List all algorithms

qgis_process list

Output all registered Providers and the algorithm IDs they provide.

2. View algorithm help

qgis_process help qgis:regularpoints

Output the algorithm description, parameter list (name, type, default value, whether optional), and output definitions.

JSON format help (recommended for AI use)

qgis_process help native:buffer --json

JSON output structure:

{
  "qgis_version": "...",
  "algorithm_details": {
    "id": "native:buffer",
    "name": "Buffer",
    "tags": ["..."]
  },
  "provider_details": {
    "id": "native",
    "name": "QGIS (native c++)"
  },
  "parameters": {
    "INPUT": {
      "name": "INPUT",
      "description": "Input layer",
      "type": {
        "id": "source",
        "name": "Vector Features",
        "acceptable_values": ["Path to a vector layer"]
      },
      "optional": false,
      "default_value": null
    },
    "DISTANCE": {
      "name": "DISTANCE",
      "description": "Distance",
      "type": {
        "id": "distance",
        "name": "Distance"
      },
      "optional": false,
      "default_value": 10
    },
    "OUTPUT": {
      "name": "OUTPUT",
      "description": "Buffered",
      "type": {
        "id": "sink",
        "name": "Vector Layer Destination"
      },
      "is_destination": true,
      "optional": false
    }
  },
  "outputs": {
    "OUTPUT": {
      "description": "Buffered",
      "type": "outputVector"
    }
  }
}

3. Run an algorithm

Basic syntax

qgis_process run <algorithm_id> -- PARAM1=VALUE1 PARAM2=VALUE2 ...

Example: buffer analysis

qgis_process run native:buffer -- INPUT=source.shp DISTANCE=2 OUTPUT=buffered.shp

Example: merge layers (multi-value parameter)

Specify the same parameter multiple times to pass a list value:

qgis_process run native:mergevectorlayers -- LAYERS=input1.shp LAYERS=input2.shp OUTPUT=merged.shp

`run` command additional options

Option	Description
`--json`	Output execution results in JSON format
`--ellipsoid=<name>`	Specify the ellipsoid, used for distance and area calculations
`--distance_units=<unit>`	Specify the distance unit
`--area_units=<unit>`	Specify the area unit
`--project_path=<path>`	Load an existing QGIS project file for use when running the algorithm

JSON format run result

qgis_process run native:buffer --json -- INPUT=source.shp DISTANCE=2 OUTPUT=buffered.shp

JSON output structure:

{
  "qgis_version": "...",
  "algorithm_details": { "id": "native:buffer" },
  "inputs": {
    "INPUT": "source.shp",
    "DISTANCE": "2",
    "OUTPUT": "buffered.shp"
  },
  "results": {
    "OUTPUT": "/full/path/to/buffered.shp"
  },
  "log": ["..."]
}

4. Pass JSON parameters via STDIN (complex parameters)

When the parameter itself is a complex object (such as a dictionary type), JSON can be passed via STDIN:

qgis_process run <algorithm_id> -

The trailing - indicates reading parameters from STDIN. The JSON must contain the "inputs" key:

echo '{"inputs": {"INPUT": "my_shape.shp", "DISTANCE": 5}}' | qgis_process run native:buffer -

Complete JSON structure (including optional configuration):

{
  "ellipsoid": "EPSG:7019",
  "distance_units": "feet",
  "area_units": "ha",
  "project_path": "/path/to/project.qgs",
  "inputs": {
    "INPUT": "my_shape.shp",
    "DISTANCE": 5,
    "SEGMENTS": 8,
    "OUTPUT": "output.shp"
  }
}

Note: When JSON is passed via STDIN, the output automatically uses JSON format.

5. Plugin management

# 列出插件
qgis_process plugins

# 启用插件
qgis_process plugins enable cartography_tools

# 禁用插件
qgis_process plugins disable cartography_tools

6. Run model files

qgis_process run /path/to/my_model.model3 -- INPUT=data.shp OUTPUT=result.shp

7. Run Python scripts

qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp

Common built-in algorithms quick reference

The following lists common built-in algorithm categories and representative IDs:

Vector general (native)

Algorithm ID	Description
`native:buffer`	Buffer analysis
`native:clip`	Clip
`native:dissolve`	Dissolve
`native:intersection`	Intersection
`native:union`	Union
`native:difference`	Difference
`native:symmetricaldifference`	Symmetric difference
`native:centroids`	Centroid
`native:convexhull`	Convex hull
`native:simplifygeometries`	Simplify geometry
`native:reprojectlayer`	Reproject
`native:mergevectorlayers`	Merge vector layers
`native:splitvectorlayer`	Split vector layer
`native:extractbyattribute`	Extract by attribute
`native:extractbylocation`	Extract by location
`native:joinattributesbylocation`	Join attributes by location
`native:fixgeometries`	Fix geometries
`native:countpointsinpolygon`	Count points in polygon
`native:voronoipolygons`	Thiessen polygons
`native:delaunaytriangulation`	Delaunay triangulation
`native:creategrid`	Create grid
`native:randomextract`	Random sampling
`native:addautoincrementalfield`	Add autoincremental field
`native:fieldcalculator`	Field calculator

Raster analysis (native / gdal)

Algorithm ID	Description
`native:rasterlayerstatistics`	Raster statistics
`native:rastersurfacevolume`	Raster surface volume
`gdal:cliprasterbyextent`	Clip raster by extent
`gdal:cliprasterbymask`	Clip raster by mask layer
`gdal:merge`	Merge rasters
`gdal:warpreproject`	Reproject raster
`gdal:contour`	Contour extraction
`gdal:polygonize`	Raster to vector
`gdal:rasterize`	Vector to raster
`gdal:hillshade`	Hillshade
`gdal:slope`	Slope analysis
`gdal:aspect`	Aspect analysis
`gdal:roughness`	Roughness
`gdal:buildvirtualraster`	Build virtual raster (VRT)

Coordinate reference system

Algorithm ID	Description
`native:reprojectlayer`	Vector reprojection
`gdal:warpreproject`	Raster reprojection
`native:assignprojection`	Assign projection (without coordinate transformation)

Point cloud (pdal)

Algorithm ID	Description
`pdal:info`	Point cloud information
`pdal:clip`	Point cloud clipping
`pdal:merge`	Point cloud merging
`pdal:thin`	Point cloud thinning
`pdal:tile`	Point cloud tiling
`pdal:boundary`	Point cloud boundary
`pdal:density`	Point cloud density
`pdal:exportraster`	Point cloud to raster
`pdal:exportvector`	Point cloud to vector

Parameter type reference

qgis_process Supported common parameter types and command-line value passing methods:

Parameter type	Description	Command-line value example
`source` / `vector`	Vector data source	File path `input.shp`、`input.geojson`
`raster`	Raster layer	File path `dem.tif`
`sink`	Vector output destination	File path `output.shp`、`output.gpkg`
`rasterDestination`	Raster output destination	File path `output.tif`
`number` / `distance` / `area`	Numeric value	`10`、`2.5`
`string`	String	`"my_value"`
`boolean`	Boolean value	`true` / `false`
`enum`	Enumeration	Numeric index `0`、`1`、`2`
`crs`	Coordinate reference system	`EPSG:4326`、`EPSG:3857`
`extent`	Spatial extent	`xmin,xmax,ymin,ymax [EPSG:code]`
`point`	Point coordinates	`x,y [EPSG:code]`
`field`	Field name	Field name string
`expression`	QGIS expression	`"field_name * 2"`
`multilayer`	Multiple layers	Specify the same parameter multiple times
`file`	File path	`/path/to/file`
`folder`	Folder path	`/path/to/folder`

Typical workflow examples

Example 1: Vector data format conversion (SHP → GeoJSON)

# 使用 ogr2ogr 风格的转换，利用 QGIS 重投影能力
qgis_process run native:reprojectlayer -- \
  INPUT=input.shp \
  TARGET_CRS=EPSG:4326 \
  OUTPUT=output.geojson

Example 2: Batch buffer + dissolve

# 第一步：缓冲区分析
qgis_process run native:buffer -- \
  INPUT=points.shp \
  DISTANCE=1000 \
  SEGMENTS=16 \
  OUTPUT=/tmp/buffered.gpkg

# 第二步：融合
qgis_process run native:dissolve -- \
  INPUT=/tmp/buffered.gpkg \
  OUTPUT=dissolved.gpkg

Example 3: Raster clipping + slope analysis

# 裁剪 DEM
qgis_process run gdal:cliprasterbymask -- \
  INPUT=dem.tif \
  MASK=boundary.shp \
  OUTPUT=/tmp/clipped_dem.tif

# 坡度分析
qgis_process run gdal:slope -- \
  INPUT=/tmp/clipped_dem.tif \
  OUTPUT=slope.tif

Example 4: Passing parameters using JSON (suitable for AI automation)

cat <<'EOF' | qgis_process run native:buffer -
{
  "ellipsoid": "EPSG:7030",
  "distance_units": "meters",
  "inputs": {
    "INPUT": "/data/roads.shp",
    "DISTANCE": 50,
    "SEGMENTS": 10,
    "END_CAP_STYLE": 0,
    "JOIN_STYLE": 0,
    "MITER_LIMIT": 2,
    "DISSOLVE": false,
    "OUTPUT": "/data/roads_buffer_50m.gpkg"
  }
}
EOF

Example 5: Parsing JSON output in a script

# 运行算法并捕获 JSON 输出
RESULT=$(qgis_process run native:buffer --json -- \
  INPUT=source.shp DISTANCE=100 OUTPUT=buffered.shp)

# 使用 jq 提取输出文件路径
OUTPUT_PATH=$(echo "$RESULT" | jq -r '.results.OUTPUT')
echo "输出文件: $OUTPUT_PATH"

Example 6: Algorithms that require a QGIS project file

qgis_process run native:printlayouttopdf \
  --project_path=/path/to/project.qgs -- \
  LAYOUT="My Layout" \
  OUTPUT=/output/map.pdf

AI usage recommendations

Recommended workflow

Discover algorithms：qgis_process list → Get all available algorithm IDs
View help：qgis_process help <algorithm_id> --json → Get the JSON of the parameter definitions
Construct parameters: Construct parameters according to the JSON help information
Execute algorithm：qgis_process run <algorithm_id> --json -- PARAM=VALUE ... or pass JSON via STDIN
Parse results: Parse the JSON output to obtain result paths and log information

Key considerations

Always use the --json option: JSON output is structured and easy to parse, making it the most AI-friendly interaction method.
Check help before constructing parameters: The parameter names and types differ for each algorithm; first use help --json to confirm the parameter definitions.
Pass numeric indexes for enumeration types: Enumeration parameters use numbers (such as 0、1) rather than text. The available_options in the help output provides the mapping from indexes to meanings.
Specify multi-value parameters multiple times: Such as LAYERS=a.shp LAYERS=b.shp(after -- , parameters do not have a leading --）。
Use STDIN JSON for complex parameters: Parameter values of dictionary type are suitable for passing via STDIN JSON.
Use absolute paths for file paths: Avoid files not being found due to an uncertain working directory.
Set in headless environments QT_QPA_PLATFORM=offscreen: Must be set on servers without a display.
Algorithms that require a project file: Some algorithms (such as print layout export) require specifying a project file via --project_path .
Cancel a running algorithm: Use CTRL+C to cancel an algorithm that is executing.
--no-python and --skip-loading-plugins can speed up startup: If you do not need algorithms provided by third-party plugins, using these two options can significantly shorten startup time.

Error handling

Algorithm does not exist:Algorithm <id> not found!
Missing required parameter:The following mandatory parameters were not specified
Invalid model file:File <path> is not a valid Processing model!
Invalid Python script:File <path> is not a valid Processing script!
Algorithm cannot be used from the command line:The "<id>" algorithm is not available for use outside of the QGIS desktop application
Project file required:The "<id>" algorithm requires a QGIS project to execute

Algorithm Provider Categories

Provider ID	Description	Source
`native`	QGIS native C++ algorithms	QGIS built-in
`qgis`	QGIS Python algorithms	QGIS built-in
`gdal`	GDAL/OGR tool wrappers	QGIS built-in
`grass`	GRASS GIS algorithms	QGIS built-in (requires GRASS installation)
`saga`	SAGA GIS algorithms	Provided by plugin
`pdal`	Point cloud processing algorithms	QGIS built-in (requires PDAL)
`3d`	3D analysis algorithms	QGIS built-in
Other	Third-party plugin providers	Provided by each plugin

Source code structure reference

Source code is located in the QGIS repository src/process/ directory:

File	Description
`main.cpp`	Program entry point
`qgsprocess.h`	`QgsProcessingExec` class definition, including command dispatch, plugin loading, algorithm execution, etc.
`qgsprocess.cpp`	Core implementation:`showUsage()`(help),`listAlgorithms()`(list),`showAlgorithmHelp()`(algorithm help),`execute()`(execute algorithm)
`CMakeLists.txt`	Build configuration

Core classes

QgsProcessingExec: command-line executor, responsible for parsing commands and arguments, loading plugins, and executing algorithms
ConsoleFeedback: inherits from QgsProcessingFeedback, handles console output and progress display, supports both text and JSON output modes
QgsProcessingExec::Flags: execution flags (UseJson、SkipPython、SkipLoadingPlugins）

Key methods

Method	Description
`run(args, logLevel, flags)`	Main entry point, parses command-line arguments and dispatches to the corresponding subcommands
`showUsage(appName)`	Output usage help
`showVersionInformation()`	Output version information
`listAlgorithms()`	List all Providers and algorithms
`listPlugins(useJson, showLoaded)`	List plugin information
`enablePlugin(name, enabled)`	Enable/disable plugins
`showAlgorithmHelp(id)`	Show algorithm help (supports text and JSON output)
`execute(algId, parameters, ...)`	Execute the core algorithm logic
`loadPlugins()`	Load Python plugins