Skip to content
QGIS SDK

Running an app: qgis-sdk run

qgis-sdk run [PATH] [--headless] [--once] [--grace SECONDS] [--title TITLE] [--qgis-prefix PATH] starts the project as a standalone PyQGIS application (decision-52 point 3, decision-69):

  • it finds QGIS the way test and dev do - --qgis-prefix, then [tool.qgis-sdk] qgis-prefix, then QGIS_PREFIX_PATH, then qgis on PATH, then this environment - and runs the project with that interpreter, because PyQGIS only imports into the Python it was built for;
  • it runs the project’s own <plugin>/__main__.py as -m <plugin> in the project root (the same entry python -m <plugin> and a built distribution’s console script use). A project without one - a Desktop plugin - runs through a generated probe in a temporary directory that imports [tool.qgis-sdk] plugin and calls the same qgis_sdk.app.main;
  • it never installs anything and never writes into the project: the install’s bindings and the SDK’s own packages go on the child’s PYTHONPATH, and the temporary directory is removed when the app exits;
  • the flags are qgis_sdk.app’s, passed through unchanged: --headless (no window, ctx.ui refuses by name), --once (start, deliver what is queued, stop - the smoke run a CI job makes), --grace (the shutdown bound) and --title;
  • the app’s exit code is the command’s, and a project that is not one or a prefix without bindings is exit 2 with the reason, before anything starts.
Terminal window
qgis-sdk run                                   # a window
qgis-sdk run --headless --once                 # CI: does this project start and stop?
qgis-sdk run --grace 5 --title "Field tools"   # a shorter shutdown bound

dev --mode standalone is a different thing on purpose: it runs the plugin inside a bare QgsApplication through the generated dev host with no app window, for a fast page/action loop. run is the app host - the one that owns the window, the loops and the shutdown bound.