QGIS installation finder¶

Use this job to find installed QGIS version for automatic definition of QDT environnement variable QDT_QGIS_EXE_PATH (used for shortcut creation).

If the environment variable is already defined and a valid QGIS installation is found by this variable, the job is skipped.

Compatibility¶

This job is compatible with:

Windows
Linux

Use it¶

Sample job configuration in your scenario file:

- name: Find installed QGIS
  uses: qgis-installation-finder
  with:
    version_priority:
      - "3.36"
    search_paths:
      - D:\\Applications\\QGIS\\
    if_not_found: error

Options¶

version_priority¶

Since multiple versions of QGIS can be easily installed on Windows, this option is used to specify the preferred QGIS version.

For example if you define:

- name: Find installed QGIS
  uses: qgis-installation-finder
  with:
    version_priority:
      - "3.34"
      - "3.36"

QDT will first use 3.34.z versions. If none are available it will use 3.36.z versions.

If multiple 3.34.z versions are available, the latest will be used. For example if 3.34.1 and 3.34.5 version are available, 3.34.5 will be used.

If any version of version_priority is available, then the most recent version found is used.

The environment variable QDT_PREFERRED_QGIS_VERSION is used as top priority if defined.

search_paths¶

This option can be used to define search paths for QGIS installation. The order of the paths is used to define which path will be used in case of multiple installation for same QGIS version.

For example if you define:

- name: Find installed QGIS
  uses: qgis-installation-finder
  with:
    version_priority:
      - "3.36"
    search_paths:
      - D:/Install/QGIS 3.36
      - D:/OtherInstall/QGIS 3.36

QDT will find two installation for version 3.36 but the first available in search_paths will be used (D:/Install/QGIS 3.36 in our case).

if_not_found¶

This option determines the action to be taken if QGIS is not found during the search process.

Possible_values:

warning (default): if no version found, a warning is displayed in QDT logs
error: if no version found, QDT stops and the other jobs are not run

How does it work¶

On Linux, QDT locates installed QGIS with which command and will search for available installation with the search_paths option.

On Windows QDT tries to locate installed versions in the directories in search_paths option. If the option is not defined, QDT will search in these directories:

%PROGRAMFILES%\\QGIS x.y.z\ (by using a regexp to get available QGIS versions)
%QDT_OSGEO4W_INSTALL_DIR% (default value : C:\\OSGeo4W)

By default, the most recent version found is used.

Schema¶

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/Guts/qgis-deployment-cli/raw/main/docs/schemas/scenario/jobs/qgis-installation-finder.json",
  "description": "Job in charge of findind installed QGIS version on computer.",
  "title": "QGIS installation finder",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "version_priority": {
        "default": "",
        "description": "Define QGIS version priority for search.",
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "if_not_found": {
        "default": "warning",
        "description": "Behavior if no QGIS installation found.",
        "enum": [
          "warning",
          "error"
        ],
        "type": "string"
      },
      "search_paths": {
        "default": "",
        "description": "Define search paths for QGIS installation.",
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}