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.

Table of Contents

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 and locate
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.