Setting The Prefix Path For Standalone Pyqgis Apps On Linux
Defining the Problem – QGIS Python apps may fail to run without configuring prefix paths
QGIS Python plugins and scripts rely on importing QGIS Python modules like qgis.core to access geospatial processing functions. However, when running QGIS Python code as standalone scripts outside of the QGIS application, the Python interpreter cannot locate the qgis Python modules by default leading to import errors.
This issue arises because the QGIS Python library files are stored in non-standard locations like /usr/share/qgis/python that are not part of the default Python search path. To successfully import and run PyQGIS modules outside QGIS, the Python prefix path needs to be configured to include the path to the qgis Python modules.
Symptoms of Missing Prefix Path Configuration
- ImportError when importing PyQGIS modules like qgis.core
- Failed script executions with module not found errors
- PyQGIS processing functions not available in Python terminal or IDEs
Setting the appropriate Linux environment variables to prepend the QGIS Python library path will resolve such errors enabling smooth executions of standalone PyQGIS scripts.
Finding QGIS Install Location – Use which qgis to locate QGIS install folder
The first step is to identify where QGIS is installed on your Linux system. This can be done using the which
command to locate the qgis executable path:
which qgis
A sample output would show the full install location:
/usr/bin/qgis
This means QGIS is installed in the /usr
folder. We need to navigate to subfolders under this base directory to find the relevant PyQGIS libraries.
Getting QGIS Install Paths via Alternative Methods
If which qgis
does not work, alternative options to find the QGIS installed location include:
- Using file search tools like
find
andlocate
- Checking standard Linux install locations like
/usr
and/opt
- Using the QGIS about dialog to get folder paths (if QGIS application launches)
Getting Relevant Folders – Identify key folders like /bin, /share/qgis/python
Within the QGIS install directory, there are two important subfolders that need to be appended to the prefix path:
- The bin folder – containing Python bindings and QGIS core libraries required for PyQGIS modules to work.
- The python folder – containing the actual qgis Python packages and modules like qgis.core that need to be imported.
For the sample QGIS install location of /usr
, these relevant paths would be:
/usr/bin
– bin folder with Python bindings for QGIS libraries/usr/share/qgis/python
– python folder with qgis PyQGIS modules
Identifying these key Python library locations is crucial for setting up the environment correctly in the next step.
Handling Multiple QGIS Versions
If you have multiple parallel QGIS installs, determine which version is targeted and get folders for that specific install only. Mixing up folders from different versions can cause compatibility issues.
Setting OS Environment Variables – Export path variables for LD_LIBRARY_PATH and PYTHONPATH
To make the QGIS Python libraries loadable outside of QGIS, their paths need to be appended to the following Linux environment variables:
- LD_LIBRARY_PATH – stores locations of Linux dynamic libraries needed to run apps.
- PYTHONPATH – stores paths to Python modules and packages available for importing.
Using the example QGIS install locations identified earlier, these variables can be exported as:
export LD_LIBRARY_PATH=/usr/bin:$LD_LIBRARY_PATH
export PYTHONPATH=/usr/share/qgis/python:$PYTHONPATH
This prepends the QGIS specific paths to the existing environment variables making the PyQGIS libraries loadable. The exports need to be added to shell startup scripts like ~/.bashrc or ~/.profile for permanence.
Prioritizing the QGIS Paths
Prepending guarantees that the QGIS libraries are searched first before system defaults. This prevents conflicts from any standard Python packages named same as PyQGIS ones.
Verifying Environment Setup – Test if Python can now import qgis modules successfully
Before proceeding to write actual PyQGIS scripts, the environment setup changes need to be verified to confirm everything is configured correctly.
This can be tested by launching Python interactive terminal and attempting to import PyQGIS modules. For example:
python
Python 3.7.0 (default, Aug 15 2022, 14:17:02)
[GCC 8.5.0] :: Linux
>>> import qgis.core
If no errors occur during the import, the prefix path is correctly set to locate qgis Python libraries. If modules are still not found, recheck paths exported in the environment variables.
Testing in Python IDEs like Spyder, PyCharm etc
The imports can also be verified by running them within Python IDEs instead of standalone terminal. This also validates if IDEs can now auto-complete PyQGIS modules for coding.
Creating a Test Script – Write a basic PyQGIS script to validate environment
Once imports work, the next validation step is to write a simple PyQGIS script that performs basic GIS operations. For example, creating a point geometry layer:
from qgis.core import QgsApplication, QgsVectorLayer
qgs = QgsApplication([], False)
qgs.initQgis()
layer = QgsVectorLayer("Point?crs=epsg:4326", "points", "memory")
prov = layer.dataProvider()
qgs.exitQgis()
The script uses PyQGIS modules to create an in-memory point layer without needing the QGIS application UI. Such test scripts should utilize key classes like QgsApplication, QgsVectorLayer etc. to thoroughly verify functionality.
Importing Auxiliary Modules
Apart from qgis.core, also test imports for other submodules like qgis.analysis, qgis.utils etc. This confirms full PyQGIS environment integration.
Running the Test Script – Execute the script to confirm PyQGIS works as standalone
Once the test script is complete, run it from the command line Python interpreter:
python test_script.py
The script should execute without any issues and you can add print statements or debuggers like pdb to validate if PyQGIS classes work as expected.
Troubleshooting errors at this stage is easier compared to later in more complex scripts or applications. Hence, always test basics first before moving to actual coding tasks.
Testing Functionality in IDEs
Also run and debug scripts within Python IDEs like VS Code and PyCharm. This confirms the IDE environments are also configured correctly to support standalone PyQGIS development.
Troubleshooting Issues – Solutions for common errors like module not found
Some common errors faced while setting up standalone PyQGIS apps and their troubleshooting suggestions are below:
ImportError: No module named qgis.core
- Confirm PYTHONPATH includes path like /usr/share/qgis/python
- Check for typos in the exported variable
- Reinstall QGIS using OS packages instead of standalone installers
Symbol not found: pygobject_new
- LD_LIBRARY_PATH does not include QGIS library path – add /usr/bin to it
- pygobject library missing – try installing pygobject OS package
Segmentation fault – module crashes unexpectedly
- Incompatible QGIS python version – compile modules against correct Python interpreters
- Try upgrading existing QGIS installation to latest version
Besides the above fixes, also ensure:
- Test scripts are run using correct Python versions – either python or python3
- OS user has read + execute access for all path locations appended
- No spaces exist in the exported variable paths
Example Codes – Sample scripts showing prefix path setup for Linux
Some Github GIST links showing practical examples of prefix path configurations and PyQGIS test scripts:
These real code samples demonstrate ways to export paths, troubleshoot issues, and test standalone setups on different Linux distributions like Ubuntu, Fedora etc.