How to use PyQGIS as standalone script on Ubuntu

Today I wanted to hack together a standalone script using PyQGIS, the QGIS Python bindings, to write a small prototype. I hadn’t written such a standalone script yet, but it seemed to be low hanging fruit. Turns out, it isn’t really straight forward on Ubuntu. Here I am going to show you how it worked for me.

Reading the relevant docs in the PyQGIS Developer Cookbook, I assumed it would be a quick copy/paste job to setup the QGIS application context inside the script. But the devil is in the detail. The docs seem to assume you installed QGIS by compiling master or something similar, controlling the place where QGIS’ resources are installed. But I am using the pre-built packages from package repo.

Here you see the most basic form of a PyQGIS script, according to the docs. It does only initialize the QGIS Application instance, nothing more. But before we can run it, we need to make sure that Python finds the imported QGIS modules.

from qgis.core import QgsApplication

# Supply path to qgis install location
QgsApplication.setPrefixPath("/usr/bin/qgis", True)

# Create a reference to the QgsApplication.  Setting the
# second argument to False disables the GUI.
qgs = QgsApplication([], False)

# Load providers

# Put your pyqgis code here:

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory

The docs tell us to use something like this on Linux to tell Python where to find the QGIS Python modules:

export PYTHONPATH=/<qgispath>/share/qgis/python

But where is this <qgispath>?

I didn’t find any docs or other help online, so I used dpkg-query -L <package_name> to locate files that have been installed with the qgis package. Turns out, QGIS on Ubuntu from repo consists of a whole lot of different packages, and also properly uses the systems own package manager to install more Python dependencies. The PyQGIS stuff is also packaged to fit into the scheme and therefore provides an independent python3-qgis package, which drops the python modules in /usr/lib/python3/dist-packages/.

Now, when I set the PYTHONPATH using

export PYTHONPATH=/usr/lib/python3/dist-packages/

and run the script from above using


I don’t get any more ModuleNotFoundError: No module named 'qgis'.

Fortunately, I don’t get any errors from missing linked libraries as anticipated in the docs.

5 2 votes
Article Rating
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

1 Comment
Newest Most Voted
Inline Feedbacks
View all comments
2 months ago

The path “/usr/lib/python3/dist-packages/” is commonly one of the defaults folders python looks up for dependencies. It can be checked with python -c "import sys; print(sys.path)"

I think the problem could be which version of python are you running by default. Depending on the Ubuntu versionpythoncould be version 2 o version 3. And you can not use python2 with QGIS 3.x

Instead of playing with the "PYTHONPATH" that could have undesired side effects, I suggest to be explicit about the python version used.python` works for me in Ubuntu 18.04 using the QGIS packages from ubuntugis.