Installation

As a stand-alone executable

Requirements

• operating system:

  • Linux (tested on Debian-based distribution)

  • Windows 10+

• network:

  • github.com

  • pypi.org

Step-by-step

1. Download the latest release from GitHub Release:

Download for Linux

Download for Windows

Download for MacOS

1. Make sure that it’s executable (typically on Linux: chmod u+x ./QGISDeploymentToolbelt_XXXXXX)

2. Elaborate your scenario (or grab the sample from the repository)

3. Run it:

   • from your favorite shell if you like the CLI - see the relevant section

   • store your scenario as scenario.qdt.yml in the same folder and double-click on the executable

Warning

MacOS version is not tested and is just here to encourage beta-testing and feedback to improve it.

---

As a Python package

Requirements

• Python 3.10+

Using pipx (recommended)

# bare
pipx install qgis-deployment-toolbelt
# to have completion commands
pipx install qgis-deployment-toolbelt[completion]

Using pip

The package is installable with pip:

pip install qgis-deployment-toolbelt
# to have completion commands
pip install qgis-deployment-toolbelt[completion]

It’s then available as a CLI: see the relevant section

Without native extensions

To match the released executables, install dulwich (Git implementation used by QDT) without its Rust extensions. Useful on workstations enforcing application allowlisting on DLLs or lacking prebuilt wheels (e.g. Windows ARM64). Consequence: Git operations are slightly slower.

PIP_NO_BINARY=dulwich PURE=1 pip install qgis-deployment-toolbelt
# with pipx, force its pip backend (recent versions default to uv when available)
PIPX_DEFAULT_BACKEND=pip PIP_NO_BINARY=dulwich PURE=1 pipx install qgis-deployment-toolbelt

On Windows (PowerShell):

$env:PIP_NO_BINARY = "dulwich"; $env:PURE = "1"
pip install qgis-deployment-toolbelt
# with pipx
$env:PIPX_DEFAULT_BACKEND = "pip"
pipx install qgis-deployment-toolbelt

Memo:

• PIP_NO_BINARY makes pip build dulwich from source

• PURE make pip skip the Rust extensions, which would otherwise be compiled if a Rust toolchain is available.

---

Using Docker

Warning

The Docker image is not a substitute for the standalone binary or Python package when deploying to end-user workstations. It is more designed for server-side and CI/CD usage only.

See details below.

The package is published as container on GitHub Container Registry (GHCR):

docker pull ghcr.io/qgis-deployment/qgis-deployment-toolbelt-cli

See container page for additional options and instructions.

Scope and limitations

QDT is designed to run on the end-user machine, not alongside it. A container is an isolated environment: it does not share the host’s desktop session, Windows registry, or shell environment. Consequently, several jobs behave differently or are entirely unavailable depending on the execution context.

Job	From a container	Comments
qplugins-downloader	X	Requires a bind mount on the cache path
qplugins-synchronizer	X	Requires a bind mount on the QGIS profiles path
qprofiles-downloader	X	Requires a bind mount on the target path
qprofiles-synchronizer	X	Requires a bind mount on the QGIS profiles path
default-profile-setter	-	Works if the QGIS profiles folder is bind-mounted
manage-env-vars	-	Writes to the mounted file but changes have no effect on already-running host processes
splash-screen-manager	-	Works if the QGIS profiles folder is bind-mounted
qgis-installation-finder	0	QGIS is not installed inside the container
shortcuts-manager	0	Relies on desktop APIs (XDG, win32com) that are unavailable inside the container

Legend:

• X: works with some configuration (see comments)

• -: works but has no effect on the host environment

• 0: does not work at all

Appropriate use cases for the Docker image

• CI/CD pipelines: validate scenario and profile.json files against the JSON schemas, or run integration tests in an isolated environment.

• Server-side pre-caching: run qprofiles-downloader and qplugins-downloader on a server to populate a shared network drive, which end-user machines then consume via the git_local or http protocol without Docker.

Example of use-cases, pre-download profiles and plugins to a shared network folder:

docker run --rm \
  -v /srv/qdt-cache:/home/qdt-srv/.cache/qgis-deployment-toolbelt \
  -v $(pwd)/scenario.qdt.yml:/home/qdt-srv/scenario.qdt.yml \
  qdt:latest deploy -s scenario.qdt.yml

For all other use cases, in particular for deploying to end-user workstations, use the standalone binary or pip install.