Running standalone QGIS3 Python scripts in MacOS/OSX

gistfile1.md

Getting started with QGIS 3.12 and Python standalone scripts in MacOS

I spent several hours to get everything working as I wanted. Here is what I did. I kind of hope someone shows up telling "there is already a tool for that", but at least I was not able to find clear instructions how to do this. Any additions/corrections are welcome.

What I tried to achieve

• Use pyenv on command line to switch between other Python versions and the one included in QGIS
• Use QGIS features from external Python script to visualize and process spatial data
• Use editor of my choice, in this case Visual studio code

Background

There were various useful links regarding the matter, but many were for old versions of QGIS and for different operating systems.

Getting started

I'm running macOS Catalina 10.15. I have installed QGIS (3.12) and pyenv (1.2.18).

To simplify paths and simplify working with different QGIS versions I have a symlink ln -s /Applications/QGIS3.12.app /Applications/QGIS.app

Making QGIS Python version work with pyenv

You can skip this part if you want to use /Applications/QGIS.app/Contents/MacOS/bin/python directly. That works too.

Setting QGIS Python version to work in pyenv is easy once you figure out that you can just create symlink

ln -s /Applications/QGIS.app/Contents/MacOS/ $(pyenv root)/qgis-python

(or whatever you want it called). This enables you to run the scripts, but it doesn't include the PYTHONPATH as expected. I'm still trying to figure out if pyenv can automatically set the PYTHONPATH when I change environment.

Set it to following

export PYTHONPATH=/Applications/QGIS.app/Contents/Resources/python 
export PYTHONPATH=$PYTHONPATH:/Applications/QGIS.app/Contents/Frameworks/Python.framework/Versions/Current/lib/python3.7
export PYTHONPATH=$PYTHONPATH:/Applications/QGIS.app/Contents/Frameworks/Python.framework/Versions/Current/lib/python3.7/lib-dynload
export PYTHONPATH=$PYTHONPATH:/Applications/QGIS.app/Contents/Frameworks/Python.framework/Versions/Current/lib/python3.7/site-packages

Settings environment variables for QGIS

These should be all the required updates to your environment variables in MacOS. It was a horror to try figure out which path exactly is required. I tried many combinations... :)

export QGIS_PREFIX_PATH=/Applications/QGIS.app/Contents/MacOS/
export QT_QPA_PLATFORM_PLUGIN_PATH=/Applications/QGIS.app/Contents/PlugIns/platforms/
export GDAL_DATA=/Applications/QGIS.app/Contents/Resources/gdal/

A sample QGIS+Python script

This is a literal Hello world that opens app with Openstreetmaps.

from qgis.core import *
from qgis.gui import *

app = QgsApplication([], True)
app.initQgis()

print(app.showSettings())

osmUrl = 'type=xyz&url=http://a.tile.openstreetmap.org/%7Bz%7D/%7Bx%7D/%7By%7D.png&zmax=19&zmin=0&crs=EPSG3857'
rlayer = QgsRasterLayer(osmUrl, 'OpenStreetMap', 'wms')

canvas = QgsMapCanvas()
canvas.setExtent(rlayer.extent())
canvas.setLayers([rlayer])
canvas.show()

app.exec_()  

app.exitQgis()

Next step is to see if this breaks any other features...

Thanks for this helpful gist! In my case (QGIS 3.16 [LTR] on macos Catalina 10.15) the Python directory seems to be
/Applications/QGIS-LTR.app/Contents/Resources/python
rather than
/Applications/QGIS.app/Contents/Frameworks/Python.framework/Versions/Current/lib/python3.7