Modern versions of QGIS comes with a handy command-line utility called qgis_process. This allows you to access and run any Processing Tool, Script or Model from the Processing Toolbox on a terminal. This is very useful for automation since it doesn’t require you to open QGIS or manually click buttons. You can run the algorithms in a headless-mode and even schedule them to run them at specific times.

This post covers the following topics

• How to launch qgis_process command on Windows, Mac and Linux.
• How to find the parameters and values for each algorithm and build your command
• Example showing how to do a spatial join on the command-line using the Join Attributes by Location algorithm
• Example showing how to run a model on the command line to automate a complex workflow

Want to follow along? You can download the data package containing all the datasets used in this post. Before running each command, make sure to replace the paths in the commands with the paths on your computer.

Running the qgis_process Command

Windows

If you have installed QGIS via the OSGeo4W installer, your installation already has the qgis_process command. The installation comes with a .bat file that will set the correct environment variables and run the command.

For the QGIS LTR version, the .bat file is located at

c:\OSGeo4W\bin\qgis_process-qgis-ltr.bat 

If you are running a non-LTR version, the script will be at the following location.

c:\OSGeo4W\bin\qgis_process-qgis.bat 

For this post, we will be using the LTR version. If you have a different version, change your path in the commands accordingly.

Open the Command Prompt from the Start menu and enter the full path to the .bat file. Press Enter. You will see the command options and help printed in the console. If you see help printed – it means you are able to successfully launch the command.

Mac

QGIS Mac installers also come with the qgis_process utility. But to launch it, you have to specify the full path to it.

For the QGIS LTR version, the command is located at

/Applications/QGIS-LTR.app/Contents/MacOS/bin/qgis_process

If you are running a non-LTR version, the command will be at the following location.

/Applications/QGIS.app/Contents/MacOS/bin/qgis_process

You can open the Terminal and enter the command as below

Linux

This will depend on your distribution, but on most Linux versions, you will have the qgis_process utility in your system path and can be launched directly from a terminal.

qgis_process

Building Your Command

The qgis_process command has the following syntax to run an algorithm.

qgis_process run <id of the algorithm or path to model> <parameters>

Let’s do a spatial join between 2 vector layers. We will carry out the Spatial Join Analysis covered in my Advanced QGIS course. Here are the steps to do this in QGIS. We will later replicate this using the qgis_process command.

We want to join the karnataka_district polygon layer with the national_highways line layer using the Join attributes by location algorithm.

You can configure the tool and click Run.

If you are using QGIS 3.24 or higher, you can now copy the command directly from the Advanced tab at the bottom of the processing dialog.

For QGIS 3.22 or older version, you can find the parameters from the Processing History. Run the algorithm and once the processing finishes, go to Processing → History.

The first row will the last command you ran. Click on the command and you will see the algorithm id and the parameters used. You now have all the information to run this tool from the command line.

We can now build the command to run qgis_process. From the output shown in the Processing History, we can see that the id of the algorithm is native:joinattributesbylocation. For each parameter, we have the parameter name and its value. Keep the following in mind when using the values displayed in building the command

• Each parameter has to be specified as a command-line flag. i.e. INPUT becomes --INPUT.
• If the value is a list, it has to be specified with a comma-separated value. i.e. [1,2] becomes 1,2
• True/False values have to be specified as as integers. i.e. Yes/True becomes 1 and No/False becomes 0

You can learn more about the parameters and values accepted by any algorithm by running the help command like below.

c:\OSGeo4W\bin\qgis_process-qgis-ltr.bat help native:joinattributesbylocation

Example: Spatial Join on the Command Line

Now let’s run the spatial join using the qgis_process command. From the previous section, we already know the algorithm id and the parameters. The full command is shown below.

Windows

The command below is suitable to run on Windows Command Prompt. Since the command is very long, we can use the line continuation character (^) to break it down over multiple lines.

c:\OSGeo4W\bin\qgis_process-qgis-ltr.bat run ^
native:joinattributesbylocation ^
--INPUT="C:/Users/ujava/Downloads/karnataka.gpkg|layername=national_highways" ^
--JOIN="C:/Users/ujava/Downloads/karnataka.gpkg|layername=karnataka_districts" ^
--PREDICATE=0 ^
--JOIN_FIELDS=DISTRICT ^
--METHOD=2 ^
--DISCARD_NONMATCHING=0 ^
--PREFIX="" ^
--OUTPUT="C:/Users/ujava/Downloads/joined.gpkg"

Run the command and qgis_process will carry out the processing. Once the command is finished, a new geopackage layer is created with the result of the spatial join.

Mac

If you are on a Mac, below is the equivalent command to do the spatial join. We use the appropriate data paths and use line continuation character (\).

/Applications/QGIS-LTR.app/Contents/MacOS/bin/qgis_process \
run \
native:joinattributesbylocation \
--INPUT="/Users/ujavalgandhi/Downloads/karnataka.gpkg|layername=national_highways" \
--JOIN="/Users/ujavalgandhi/Downloads/karnataka.gpkg|layername=karnataka_districts" \
--PREDICATE=0 \
--JOIN_FIELDS=DISTRICT \
--METHOD=2 \
--DISCARD_NONMATCHING=0 \
--PREFIX="" \
--OUTPUT="/Users/ujavalgandhi/Downloads/joined.gpkg"

Linux

Linux command is similar to Mac but we use appropriate data and program paths

qgis_process \
run \
native:joinattributesbylocation \
--INPUT="/home/ujaval/Downloads/karnataka.gpkg|layername=national_highways" \
--JOIN="/home/ujaval/Downloads/karnataka.gpkg|layername=karnataka_districts" \
--PREDICATE=0 \
--JOIN_FIELDS=DISTRICT \
--METHOD=2 \
--DISCARD_NONMATCHING=0 \
--PREFIX="" \
--OUTPUT="/home/ujaval/Downloads/joined.gpkg"

Example: Running a Model on the Command Line

qgis_process can also run a model from the command-line. This is very helpful where you have a created a model in the QGIS Modeler and want to automate running the workflow.

We will take the example model for Aggregating Piracy Incidents from my Advanced QGIS course and see how it can be run from the command line. The QGIS models are saved as a .model file and the data package contains the piracy_hexbin.model3 file that can be used to run the command.

We first use the help command to find out the required parameters.

c:\OSGeo4W\bin\qgis_process-qgis-ltr.bat help ^  c:/Users/ujava/Downloads/piracy_hexbin.model3

Note that the model uses the Project CRS defined in a QGIS Project. qgis_process command also has an option --PROJECT_PATH to specify a project file which will be used when the model is executed. The example project file is also included in the data package. Using this information, we can now build the command using the parameters and run it like below.

c:\OSGeo4W\bin\qgis_process-qgis-ltr.bat run ^
c:/Users/ujava/Downloads/piracy_hexbin.model3 ^
--baselayer="C:/Users/ujava/Downloads/maritime_piracy.gpkg|layername=ne_10m_land" 
--inputpoints="C:/Users/ujava/Downloads/maritime_piracy.gpkg|layername=ASAM_events" 
--gridsize=250000 
--native:countpointsinpolygon_1:Aggregated="C:/Users/ujava/Downloads/counts.gpkg" 
--PROJECT_PATH="C:/Users/ujava/Downloads/maritime_piracy.qgz"

You will see that the model executed 5 algorithms and processed the inputs into an output layer.

Mac

The same model can be run on a mac with the following syntax.

/Applications/QGIS-LTR.app/Contents/MacOS/bin/qgis_process run \
/Users/ujavalgandhi/Downloads/piracy_hexbin.model3 \
--baselayer="/Users/ujavalgandhi/Downloads/maritime_piracy.gpkg|layername=ne_10m_land" \
--inputpoints="/Users/ujavalgandhi/Downloads/maritime_piracy.gpkg|layername=ASAM_events" \
--gridsize=250000 \
--native:countpointsinpolygon_1:Aggregated="/Users/ujavalgandhi/Downloads/counts.gpkg" \
--PROJECT_PATH="/Users/ujavalgandhi/Downloads/maritime_piracy.qgz"

Linux

On a linux system, the model can be invoked with a similar command.

qgis_process run \
/home/ujaval/Downloads/piracy_hexbin.model3 \
--baselayer="/home/ujaval/Downloads/maritime_piracy.gpkg|layername=ne_10m_land" \
--inputpoints="/home/ujaval/Downloads/maritime_piracy.gpkg|layername=ASAM_events" \
--gridsize=250000 \
--native:countpointsinpolygon_1:Aggregated="/home/ujaval/Downloads/counts.gpkg" \
--PROJECT_PATH="/home/ujaval/Downloads/maritime_piracy.qgz"

The qgis_process is a welcome addition to your GIS-toolkit. As you move towards automation, this little tool fills an important gap that allows you to automate your workflows. If you found this post helpful and end up using this tool in your work – please let me know in the comments!