Getting started with using Python to automate QGIS workflows can be a bit of a challenge at first, but fortunately the resources below can help accelerate the learning process and are really helpful to refer to even if you are an expert Python user. The PyQGIS cookbook is the best place to start for learning how to utilize the QGIS Python libraries in your scripts while the PyQGIS API documentation is an extremely useful comprehensive guide that describes every class and method that the API provides access to.
PyQGIS Introductory 'Cook Book':
https://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/
PyQGIS 3.x API Documentation:
https://qgis.org/pyqgis/
PyQGIS 2.x - 3.x API Break Documentation:
https://qgis.org/api/api_break.html
Configuring QGIS and Python on a Windows Computer
Please note that portions of the text that are colored red in the instructions below should be modified after copying and pasting to reflect the correct version of QGIS that you have installed on your computer.
- Install the standalone QGIS application (not the OS Geo bundle with QGIS) from https://qgis.org/en/site/forusers/download.html if you have not done so already
- Identify the path to the Python executable that was installed with QGIS (it should be at C:\Program Files\QGIS 3.14\apps\Python37). Navigate to this location in your file system and make a duplicate copy of the python.exe file. Name this duplicate copy of the Python executable python3qgis to distinguish it from other installations of Python that might already exist on your computer.
- In the search bar located in the left portion of the task bar at the bottom of your screen, search for "advanced system settings" and then click the "View Advanced System Settings" button that shows up in your results. In the window that appears, click on "Environmental Variables...". **Please note that you will need administrative privileges on the computer you are working on in order to complete this step.
- In the Environmental Variables window, click on the row for the Path variable under User Settings to highlight it in blue. Add the path to the QGIS Python executable (which you copied in step 2 above) to your path, by clicking the Edit button, than the New button, and pasting in the QGIS Python executable path in the blank row that your cursor has been moved to. Once you have done this click OK to return to the Environmental Variables window
- Now click the New button under User Variables. In the new window that appears, type PYTHONPATH for the Variable Name and paste C:\Program Files\QGIS 3.14\apps\qgis\python;C:\Program Files\QGIS 3.14\apps\qgis\python\plugins;C:\Program Files\QGIS 3.14\apps\Qt5\plugins;C:\Program Files\QGIS 3.14\share\gdal; in the Variable Value field, then click OK.
- Now click OK in the Environmental Variables window and in the System Settings window to save the changes that you've made.
- To verify your QGIS Python instance can now be run outside of the QGIS environment and used to develop external scripts, open a new Command Prompt window. In this new window type python3qgis. This will start Python in the Command Prompt environment. Now type from qgis.core import * and press Enter on your keyboard. If you see your Command Prompt jump down to a new line after a few seconds without generating an error than you have verified that you are able to QGIS Python libraries in your script.
- You should now be able to use any integrated development environment (IDE) software to write a Python script that utilizes QGIS Python libraries. To make sure that your IDE calls the correct Python executable for any scripts that you write, make sure the path to its default Python installation is the path python3qgis Python executable that was created in step 2 above. Before starting a new script make sure that you refer to https://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/intro.html#using-pyqgis-in-standalone-scripts as this contains essential information about structuring your script to ensure that the QGIS Python libraries can be used successfully. If you do not already have an IDE application installed that can be used for Python development you can continue with the steps below which describe how to install and use Atom to create and run Python scripts that reference QGIS Python libraries.
- Visit https://atom.io/ and click the Download button to download the Atom installation files on your computer. Double click on the installion file to install Atom.
- After Atom has finished installing, open the application. Click on File > Settings to open the application settings window. In the Settings window, click the Install button and then in the search bar that appears on the Install page type atom python run. The atom-python-run package should be the first one that appears in a list of search results. Click the Install button for the atom-python-run package. Once it is installed, click the Settings button for this package. On the package settings page find the text field under the F5 Comman heading, and paste in the following text: python3qgis {file}. This configuration will allow you to easily run a script that you are working on in Atom using the python3qgis Python executable on your computer by hitting the F5 button on you keyboard.
- Now that the atom-python-run package has been configured, click File > New File to create a new blank Python script file for you to work in. This file will open in a new tab within Atom. As soon as it opens click FIle > Save to open the file save window. In this window selection the location on your file system where you want the script to be stored and select a name for you script. Please note that the file name must end in .py in order for it to be correctly treated as a Python file.
- Once your script has been successfully saved, you can now start to write your Python code in the file. If you want to verify that everything is working correctly type the following for your first line of code: from qgis.core import *. Next, hit the F5 button on your keyboard to automatically save and run the script (please note you may need to make sure that the Fn button on your keyboard is on for the F5 key to call the function correctly). If everything is working properly you should see a Python shell appear. After a few seconds the text Process returned 0 (0x0) execution time : 0.123 s should appear in the shell if the code was executed successfully and the QGIS core library was imported without any issues. If instead of this message you notice an error or the Python does not appear at all when you hit F5, please review the instructions above to look for any place where a step might have been missed. If everything is working correctly you can now proceed with writing your script
Please note that portions of the text that are colored red in the instructions below should be modified after copying and pasting to reflect the correct version of QGIS that you have installed on your computer.
