Skip to content

qgis_configuration.rst

Latest commit

 

History

History
3059 lines (2248 loc) · 123 KB

qgis_configuration.rst

File metadata and controls

3059 lines (2248 loc) · 123 KB
Raw

QGIS Configuration

.. only:: html

   .. contents::
      :local:
      :depth: 2

QGIS is highly configurable. Through the :menuselection:`Settings` menu, it provides different tools to:

.. index:: Options, Configuration

Options

options Some basic options for QGIS can be selected using the :guilabel:`Options` dialog. Select the menu option :menuselection:`Settings -->` options :menuselection:`Options`. You can modify the options according to your needs. Some of the changes may require a restart of QGIS before they will be effective.

The tabs where you can customize your options are described below.

Note

Plugins can embed their settings within the Options dialog

While only Core settings are presented below, note that this list can be extended by :ref:`installed plugins <plugins>` implementing their own options into the standard Options dialog. This avoids each plugin having their own config dialog with extra menu items just for them...

General Settings

img/options_general.png

General Settings

.. index:: Overwrite language

Override System Locale

By default, QGIS relies on your Operating System configuration to set language and manipulate numerical values. Enabling this group allows you to customize the behavior.

A summary of the selected settings and how they would be interpreted is displayed at the bottom of the frame.

Application

Project files

img/project_files_settings.png

Project Files Settings

Project Trust

These options control how QGIS handles execution of scripts in project files. Embedded code includes :ref:`macros <project_macros>`, :ref:`custom expression functions <vector_expressions>`, :ref:`actions <actions_menu>` and :ref:`attribute form initialization code <form_custom_functions>`. QGIS allows you to manage trust on a per-project or per-folder basis. When a project or folder is trusted, this applies to all embedded scripts contained within. Trust cannot be granted to individual scripts.

img/project_trust_general.png

Project Trust Settings

.. index:: Environment variables

System Settings

SVG paths

Add or Remove :guilabel:`Path(s) to search for Scalable Vector Graphic (SVG) symbols`. These SVG files are then available to symbolize or label the features or decorate your map composition.

Also read :ref:`embedded_file_selector` for different ways to refer to svg files in a QGIS path.

Plugin paths

Add or Remove :guilabel:`Path(s) to search for additional C++ plugin libraries`.

Documentation paths

Add or Remove :guilabel:`Documentation Path(s)` to use for QGIS help. By default, a link to the official online User Manual corresponding to the version being used is added (i.e., https://docs.qgis.org/§qgis_short_version/$qgis_locale/docs/user_manual/). You can however add other links and prioritize them from top to bottom: each time you click on a :guilabel:`Help` button in a dialog, the topmost link is checked and if no corresponding page is found, the next one is tried, and so on.

Note

Documentation is versioned and translated only for QGIS Long Term Releases (LTR), meaning that if you are running a regular release (eg, QGIS 3.0), the help button will by default open the next LTR manual page (ie. 3.4 LTR), which may contain description of features in newer releases (3.2 and 3.4). If no LTR documentation is available then the testing doc, with features from newer and development versions, is used.

Settings

It helps you :guilabel:`Reset user interface to default settings (restart required)` if you made any :ref:`customization <sec_customization>`.

Environment

img/options_system.png

System environment variables

System environment variables can be viewed, and many configured, in the Environment group. This is useful for platforms, such as Mac, where a GUI application does not necessarily inherit the user's shell environment. It's also useful for setting and viewing environment variables for the external tool sets controlled by the Processing toolbox (e.g., GRASS), and for turning on debugging output for specific sections of the source code.

Check checkbox :guilabel:`Use custom variables (restart required - include separators)` and you can symbologyAdd Add and symbologyRemove Remove environment variables. For each new item, you can configure a :guilabel:`Variable` name, its :guilabel:`Value` and the :guilabel:`Apply` method to use, among which:

Already defined environment variables are displayed in :guilabel:`Current environment variables`, and it's possible to filter them by activating checkbox :guilabel:`Show only QGIS-specific variables`.

User Profiles Settings

Note

For more information on how to manage user profiles, please read the dedicated section at :ref:`user_profiles`.

.. index:: CRS, On-the-fly reprojection

CRS and Transforms Settings

Note

For more information on how QGIS handles layer projection, please read the dedicated section at :ref:`label_projections`.

CRS Handling

In the crs :guilabel:`CRS Handling` tab you can configure which CRS will be used for a new project or layer.

img/options_crs.png

CRS Settings

CRS for Projects

There is an option to automatically set new project’s CRS:

The choice will be saved for use in subsequent QGIS sessions. The Coordinate Reference System of the project can still be overridden from the :menuselection:`Project --> Properties... --> CRS` tab.

CRS for Layers

:guilabel:`Default CRS for layers`: select a default CRS to use when you create a layer

You can also define the action to take when a new layer is created, or when a layer without a CRS is loaded.

Accuracy Warnings

:guilabel:`Only show CRS accuracy warnings for inaccuracies which exceed` a given distance: occurs when you are explicitly creating or modifying a dataset and select a CRS based on a datum ensemble with lower accuracy. The default is to Always show the warning if any inaccuracy.

unchecked :guilabel:`Show CRS accuracy warning for layers in project legend`: If checked, any layer with a CRS with accuracy issues (i.e., a dynamic crs with no coordinate epoch available, or a CRS based on a datum ensemble with inherent inaccuracy exceeding the user-set limit) will have the indicatorLowAccuracy warning icon in the :guilabel:`Layers` panel reflecting that it is a low-accuracy layer.

This is designed for use in engineering, BIM, asset management, and other fields where inaccuracies of meter/submeter level are potentially very dangerous or expensive!

unchecked :guilabel:`Planimetric measurements`: sets the default for the :ref:`planimetric measurements <measurements_ellipsoid>` property for newly created projects.

.. index:: CRS, Datum transformation, Reprojection

Coordinate Transforms

The transformation :guilabel:`Coordinate Transforms` tab helps you set coordinate transformations and operations to apply when loading a layer to a project or reprojecting a layer.

img/options_transformations.png

Transformations settings

Default Datum Transformations

Here you can control whether reprojecting layers to another CRS should be:

You can symbologyAdd Add, symbologyRemove Remove or toggleEditing Edit transformations, which will be used in any newly created project.

User Defined CRS

The customProjection :guilabel:`User Defined CRS` tab helps you to define a custom CRS which must conform to a WKT or Proj string format.

img/options_defined_crs.png

User Defined CRS

Set a :guilabel:`Name` and use symbologyAdd Add new CRS. If you want to delete an existing one you can use symbologyRemove Remove CRS.

Definition

Test

Here you can test your created CRS definition by Latitude and Longitude. Use a known coordinate to control if your definition is accurate.

Data Sources settings

img/options_data_sources.png

Data Sources settings

Feature attributes and table

Tip

Improve opening of big data attribute table

When working with layers with big amount of records, opening the attribute table may be slow as the dialog request all the rows in the layer. Setting the :guilabel:`Attribute table behavior` to Show features visible on map will make QGIS request only the features in the current map canvas when opening the table, allowing a quick data loading.

Note that data in this attribute table instance will be always tied to the canvas extent it was opened with, meaning that selecting Show All Features within such a table will not display new features. You can however update the set of displayed features by changing the canvas extent and selecting Show Features Visible On Map option in the attribute table.

Data source handling

Localized data paths

It is possible to use localized paths for any kind of file based data source. They are a list of paths which are used to abstract the data source location. For instance, if :file:`C:\\my_maps` is listed in the localized paths, a layer having :file:`C:\\my_maps\\my_country\\ortho.tif` as data source will be saved in the project using :file:`localized:my_country\\ortho.tif`.

The paths are listed by order of preference, in other words QGIS will first look for the file in the first path, then in the second one, etc.

Hidden browser paths

This widget lists all the folders you chose to hide from the :ref:`Browser panel <browser_panel>`. Removing a folder from the list will make it available in the :guilabel:`Browser` panel.

GDAL Settings

GDAL is a data exchange library for geospatial data that supports a large number of vector and raster formats. It provides drivers to read and (often) write data in these formats. The :guilabel:`GDAL` tab exposes the drivers for raster and vector formats with their capabilities.

GDAL raster and vector drivers

The :guilabel:`Raster Drivers` and :guilabel:`Vector Drivers` tabs allow you to define which GDAL driver is enabled to read and/or write files, as in some cases more than one GDAL driver is available.

img/options_gdal.png

GDAL Settings - Raster drivers

Tip

Double-click a raster driver that allows read and write access (rw+(v)) opens the :ref:`Edit Create options <gdal_createoptions>` dialog for customization.

Raster driver options

This frame provides ways to customize the behavior of raster drivers that support read and write access:

  • :guilabel:`Edit create options`: allows you to edit or add different profiles of file transformation, i.e., a set of predefined combinations of parameters (type and level of compression, BIGTIFF support, blocks size, overview, colorimetry, alpha...) to use when outputting raster files. The parameters depend on the driver.

    img/gdalCreateOptions.png

    Sample of create options profile (for GeoTiff)

    The upper part of the dialog lists the current profile(s) and allows you to add new ones or remove any of them. You can also reset the profile to its default parameters if you have changed them. Some drivers (eg, GeoTiff) have some sample of profiles you can work with.

    At the bottom of the dialog:

.. index:: Rendering

Rendering Settings

The rendering :guilabel:`Rendering` tab provides settings for controlling layers rendering in the map canvas.

img/options_rendering.png

Rendering settings

Rendering Behavior

Rendering Quality

Vector rendering settings

The polygonLayer :guilabel:`Vector` tab contains specific settings for rendering vector layers.

img/options_rendering_vector.png

Vector rendering settings

Raster rendering settings

The raster :guilabel:`Raster` tab contains specific settings for rendering raster layers.

img/options_rendering_raster.png

Raster rendering settings

Under :guilabel:`Bands and Resampling`:

:guilabel:`Contrast Enhancement` options can be applied to :guilabel:`Single band gray`, :guilabel:`Multi band color (byte/band)` or :guilabel:`Multi band color (>byte/band)`. For each, you can set:

  • the :guilabel:`Algorithm` to use, whose values can be 'No stretch', 'Stretch to MinMax', 'Stretch and Clip to MinMax' or 'Clip to MinMax'
  • the :guilabel:`Limits (minimum/maximum)` to apply, with values such as 'Cumulative pixel count cut', 'Minimum/Maximum', 'Mean +/- standard deviation'.

The :guilabel:`Contrast Enhancement` options also include:

Canvas and Legend Settings

img/options_canvas_legend.png

Canvas & Legend settings

These properties let you set:

Note

Rendering in layouts is not affected by the :guilabel:`Respect screen DPI` setting; it always respects the specified DPI for the target output device. Also note that this setting uses the physical screen DPI as reported by the operating system, which may not be accurate for all displays.

.. index:: Map tools

Map tools Settings

img/options_map_tools.png

Map tools settings

Measurements, Coordinate and Bearing Display

This section provides ways to configure default units parameters:

The global options can be overridden at the project level, :ref:`here <measurements_ellipsoid>` for measurement units and :ref:`here <coordinate_and_bearing>` for coordinate and bearing formatting.

Identify tool

This group offers some options regarding the behavior of the :ref:`Identify tool <identify>`.

Measure tool

Measure Tool Copy Settings

These settings allow you to control the behavior of the :guilabel:`Copy` button in the measure Measure Line window. You can choose to checkbox :guilabel:`Include header` to keep column names, and you can also select :guilabel:`Separator` of your choice. You can also choose checkbox :guilabel:`Always use decimal point` to keep your coordinates copied to the clipboard with a dot as a decimal separator, even if your language settings in QGIS options are set up to use a comma. In this case, if you don't have the :guilabel:`Always use decimal point` option checked, you will be unable to select comma as a field separator.

Panning and zooming

Predefined scales

Here, you find a list of predefined scales to display by default in the scale-related drop-down widgets, such as the status bar :guilabel:`Scale`, the visibility scales selector or secondary 2D map view settings,... With the symbologyAdd and symbologyRemove buttons you can add or remove your personal scales. You can also import or export scales from/to a .XML file. Note that you still have the possibility to remove your changes and reset to the predefined list.

From the project properties dialog, you can also set your own list of scales, overriding this global one in the widgets.

.. index:: Digitizing configuration

Digitizing settings

img/options_digitizing.png

Digitizing settings

This tab helps you configure general settings when :ref:`editing vector layer <editingvector>` (attributes and geometry).

Feature creation

Measurements

Rubberband

Snapping

Vertex markers

Curve offset tool

The next options refer to the offsetCurve Offset Curve tool in :ref:`sec_advanced_edit`. Through the various settings, it is possible to influence the shape of the line offset.

  • :guilabel:`Join style`: specifies whether 'Round', 'Miter' or 'Bevel' joins should be used when offsetting corners
  • :guilabel:`Quadrant segments`: controls the number of line segments to use to approximate a quarter circle when creating rounded offsets
  • :guilabel:`Miter limit`: Sets the maximum distance from the offset geometry to use when creating a mitered join as a factor of the offset distance (only applicable for miter join style)
  • :guilabel:`End cap style`: controls how line endings are handled; they can be 'Round', 'Flat' or 'Square'.

Tracing

By activating the checkbox :guilabel:`Convert tracing to curve` you can create curve segments while digitizing. Keep in mind that your data provider must support this feature.

.. index:: Elevation

Elevation settings

img/options_elevation.png

Elevation settings

In elevationProfile :guilabel:`Elevation` menu, you can set a specific color to use as the :guilabel:`Background color` for :ref:`elevation profiles <label_elevation_profile_view>`. This can make the chart more readable for certain datasets, e.g., point clouds with RGB coloring, where the default background color is too similar to point colors to be easily discernible. If unchanged, the elevation profiles will continue to display using the standard system background color.

.. index:: 3D

3D settings

img/options_3d.png

3D settings

The 3d :guilabel:`3D` menu helps you configure some default settings to use for any :guilabel:`3D Map view`. These can refer to:

.. index:: Colors

Colors settings

img/options_colors.png

Colors settings

This menu allows you to create or update palettes of colors used throughout the application in the :ref:`color selector widget <color_widget>`. You can choose from:

By default, :guilabel:`Recent colors`, :guilabel:`Standard colors` and :guilabel:`Project colors` palettes can not be removed and are set to appear in the color button drop-down. Custom palettes can also be added to this widget thanks to the :guilabel:`Show in Color Buttons` option.

For any of the palettes, you can manage the list of colors using the set of tools next to the frame, ie:

Double-click a color in the list to tweak or replace it in the :ref:`Color Selector <color-selector>` dialog. You can also rename it by double-clicking in the :guilabel:`Label` column.

.. index:: Fonts

Fonts Settings

img/options_fonts.png

Fonts settings

The :guilabel:`Fonts` tab provides support to manage fonts used across the projects:

  • :guilabel:`Font Replacements`: gives ability to populate a list of automatic font replacements to apply when loading projects or styles, allowing better support for projects and styles to be used across different operating systems (e.g., replace "Arial" with "Helvetica").

  • :guilabel:`User Fonts`: Allows you to place TTF or OTF fonts in the :file:`fonts` sub-folder of the :ref:`user profile <user_profiles>`. These fonts can be automatically loaded at QGIS startup time. This provides a way to use fonts without requiring them to be installed on an operating system level, which is often blocked in enterprise environments. The panel lists all installed user fonts and allows you to manage (i.e., remove) previously installed user fonts.

    It is also possible to checkbox :guilabel:`Automatically download missing, freely-licensed fonts`: E.g., if you open a project or style, or try to load a vector tile layer that references fonts that aren’t currently available, then a hard-coded list of freely licensed fonts to download via URL is consulted to determine whether it’s possible to automatically download the font to the user profile font directory (with notification of the font license).

Layouts settings

img/options_layouts.png

Layouts settings

Layout defaults

Grid appearance

Grid and guide defaults

Layout Paths

.. index:: Variables

Variables settings

The :guilabel:`Variables` tab lists all the variables available at the global-level.

It also allows the user to manage global-level variables. Click the symbologyAdd button to add a new custom global-level variable. Likewise, select a custom global-level variable from the list and click the symbologyRemove button to remove it.

More information about variables in the :ref:`general_tools_variables` section.

img/options_variables_global.png

Variables settings

.. index:: Authentication

Authentication settings

In the :guilabel:`Authentication` tab you can set authentication configurations and manage PKI certificates. See :ref:`authentication_index` for more details.

To manage authentications, you can use the list of tools next to the frame, ie:

  • symbologyAdd Add new authentication configuration
  • symbologyRemove Remove selected authentication configuration
  • symbologyEdit Edit selected authentication configuration
../auth_system/img/options_authentication.png

Authentication settings

.. index:: Proxy, Network

Network settings

General

img/options_network.png

Network and proxy settings

Cache settings

Defines the :guilabel:`Directory` and a :guilabel:`Size` for the cache specified in megabytes. You can clear the value to enable the :guilabel:`Smart cache size`, which sets the maximum cache size based on available disk space. Also offers tools to :guilabel:`automatically clear the connection authentication cache on SSL errors (recommended)`.

Proxy for web access

Credentials of proxy are set using the :ref:`authentication widget <authentication>`.

Excluding some URLs can be added to the text box below the proxy settings (see :numref:`Figure_Network_Tab`). No proxy will be used if the target url starts with one of the string listed in this text box.

If you need more detailed information about the different proxy settings, please refer to the manual of the underlying QT library documentation at ProxyType-enum.

Tip

Using Proxies

Using proxies can sometimes be tricky. It is useful to proceed by 'trial and error' with the above proxy types, to check if they succeed in your case.

.. index:: GPS

GPS settings

The gps :guilabel:`GPS` dialog helps you configure GPS devices connections and properties in QGIS. It also provides settings for GPS tracking and data digitizing.

img/options_gps.png

GPS settings

You can specify:

GPSBabel

GPSBabel converts waypoints, tracks, and routes between popular GPS receivers such as Garmin or Magellan and mapping programs like Google Earth or Basecamp. Literally hundreds of GPS receivers and programs are supported. QGIS relies on GPSBabel to interact with these devices and :ref:`manipulate their data <gps_algorithms>`.

For details on how-to, please refer to :ref:`load_from_device`.

.. index:: Search widget, Locator

Locator settings

search The :guilabel:`Locator` tab lets you configure the :ref:`Locator bar <locator_bar>`, a quick search widget available on the status bar to help you perform searches in the application. It provides some default filters (with prefix) to use:

img/options_locator.png

Locator settings

In the dialog, you can:

  • customize the filter :guilabel:`Prefix`, i.e., the keyword to use to trigger the filter
  • set whether the filter is :guilabel:`Enabled`: the filter can be used in the searches and a shortcut is available in the locator bar menu
  • set whether the filter is :guilabel:`Default`: a search not using a filter returns results from only the default filters categories.
  • Some filters provide a way to configure the number of results in a search.

The set of default locator filters can be extended by plugins, eg for OSM nominatim searches, direct database searching, layer catalog searches, ...

Acceleration settings

OpenCL acceleration settings.

img/options_acceleration.png

Acceleration settings

Depending on your hardware and software, you may have to install additional libraries to enable OpenCL acceleration.

IDE settings

Under :guilabel:`GitHub access token`, you can generate a personal token allowing you to share code snippets from within the Python code editor. More details on GitHub authentication

Code Editor settings

In the codeEditor :guilabel:`Code Editor` tab, you can control the appearance and behaviour of code editor widgets (Python interactive console and editor, expression widget and function editor, ...).

img/options_codeeditor.png

Code Editor settings

At the top of the dialog, a widget provides a live preview of the current settings, in various coding languages (Python, QGIS expression, HTML, SQL, JavaScript). A convenient way to adjust settings.

Python settings

The runConsole :guilabel:`Python` settings help you manage and control the behavior of the Python editors (:ref:`interactive console <interactive_console>`, :ref:`code editor <console_editor>`, :ref:`project macros <project_macros>`, :ref:`custom expressions <function_editor>`, ...). It can also be accessed using the options Options... button from:

img/options_pythonconsole.png

Python settings

You can specify:

Under :guilabel:`APIs`, you can specify which APIs your code should rely on:

The :guilabel:`External Editor` group allows you to provide command line instructions to launch an external Python code editor, given a file name, a line and column number. If empty, the default system editor will be used.

Processing settings

The processingAlgorithm :guilabel:`Processing` tab provides you with general settings of tools and data providers that are used in the QGIS Processing framework. More information at :ref:`processing.options`.

img/options_processing.png

Processing settings

Advanced settings

img/options_advanced.png

Advanced settings

All the settings related to QGIS (UI, tools, data providers, Processing configurations, default values and paths, plugins options, expressions, geometry checks...) are saved in a :file:`QGIS/QGIS4.ini` file under the active :ref:`user profile <user_profiles>` directory. Configurations can be shared by copying this file to other installations.

From within QGIS, the :guilabel:`Advanced` tab offers a way to manage these settings through the :guilabel:`Advanced Settings Editor`. After you promise to be careful, the widget is populated with a tree of all the existing settings, and you can edit their value. Right-click over a setting or a group and you can delete it (to add a setting or group, you have to edit the :file:`QGIS4.ini` file). Changes are automatically saved in the :file:`QGIS4.ini` file.

Warning

Avoid using the Advanced tab settings blindly

Be careful while modifying items in this dialog given that changes are automatically applied. Doing changes without knowledge can break your QGIS installation in various ways.

.. index:: User profile

Working with User Profiles

The concept

The :menuselection:`Settings --> User Profiles` menu provides functions to set and access user profiles. A user profile is a unified application configuration that allows to store in a single folder:

By default, a QGIS installation contains a single user profile named default. But you can create as many user profiles as you want:

  1. Click the :menuselection:`Settings --> User Profiles --> New profile...` entry.

  2. You'll be prompted to provide a profile name, creating a folder of the same name under :file:`~/<UserProfiles>/` where:

    The user profile folder can be opened from within QGIS using the :guilabel:`Open Active Profile Folder`.

  3. A new instance of QGIS is started, using a clean configuration. You can then set your custom configurations.

If you have more than one profile in your QGIS installation, the name of the active profile is shown in the application title bar between square brackets.

As each user profile contains isolated settings, plugins and history they can be great for different workflows, demos, users of the same machine, or testing settings, etc. And you can switch from one to the other by selecting them in the :menuselection:`Settings --> User Profiles` menu. You can also run QGIS with a specific user profile from the :ref:`command line <label_commandline>`.

Tip

Run QGIS under a new user profile to check for bug persistence

Bugs you may encounter with functions in QGIS can be related to leftovers in the current user profile. Running QGIS under another user profile can help you solve them or check the origin of the issue. The general advice is to launch QGIS under a new user profile, thus a cleaner configuration, and run the commands again.

If the bug prevents you to create a new user profile from within the :menuselection:`Settings --> User Profiles` menu, you can either:

Setting user profile

By default, QGIS opens a new session with the profile of the last closed session. This, among other settings, can be customized in :menuselection:`Settings -->` options :menuselection:`Options -->` user :menuselection:`User Profiles` tab:

img/options_userprofiles.png

User profiles settings

.. index:: Project properties
   single: Project; Properties
   single: Settings; Project

Project Properties

In the properties window for the project under :menuselection:`Project --> Project Properties`, you can set project-specific options. The project-specific options overwrite their equivalent in the :guilabel:`Options` dialog described above.

General Properties

In the general :guilabel:`General` tab, the :guilabel:`General settings` let you:

  • see the location of the project file
  • set the folder for the project home (available in the :guilabel:`Project home` item of the :guilabel:`Browser` panel). The path can be relative to the folder of the project file (type it in) or absolute. The project home can be used for storing data and other content that is useful for the project. Convenient when dataset and project files are not stored at the same place. If not filled, the :guilabel:`Project home` defaults to the project file folder.
  • give a title to the project beside the project file path
  • choose the color to use for features when they are selected
  • choose the background color: the color to use for the map canvas
  • set whether the path to layers in the project should be saved as absolute (full) or as relative to the project file location. You may prefer relative path when both layers and project files can be moved or shared or if the project is accessed from computers on different platforms.
  • choose to avoid artifacts when project is rendered as map tiles. Note that checking this option can lead to performance degradation.
  • :guilabel:`Remember attribute tables windows and docks between sessions`: If checked for a project, then any opened attribute tables will be saved into the project and immediately restored when loading that project. This can improve workflows when you constructed a project with a particular set of attribute table configurations for your requirements, and re-setting up these attribute tables is a hassle.

Calculating areas and distances is a common need in GIS. However, these values are really tied to the underlying projection settings. The :guilabel:`Measurements` frame lets you control these parameters. You can indeed choose:

  • the :guilabel:`Scale calculation method`: when working on large map extents, especially with geographic CRS, the scale bar may not reflect actual distance measurement depending on the latitude at which the calculation is done. This setting helps you define the area you want the calculation to be taken from:

    Changing the scale calculation method has the following impacts:

    • New layout scale bars will default to the project's scale calculation method
    • The scale calculations for the status bar widget and map renders will be changed (including flow on impacts like the value of @map_scale variable, scale based visibility of layers and symbols)
    • This also affects QGIS server map rendering
    • Processing algorithms which render maps will respect the project's scale calculation method

    Note

    Symbology sizes in map units are NOT affected by this setting.

The :guilabel:`Coordinate and Bearing display` allows you to customize the display of:

  • the coordinates shown in the :guilabel:`Coordinates` box on QGIS status bar and in the :guilabel:`Derived` section of the identify Identify features tool's results
  • the bearing value displayed in the status bar for the map canvas panning direction and by the measureBearing Measure bearing tool.

Available parameters are:

img/project_general.png

General tab of the Project Properties dialog

Metadata Properties

The editMetadata :guilabel:`Metadata` tab provides you with options to create and edit a metadata report on your project. See :ref:`metadatamenu` for more information.

View Settings

img/project_viewsettings.png

View Settings tab of the Project Properties dialog

The overlay :guilabel:`View Settings` tab provides means to control the project map canvas. You can:

CRS Properties

Note

For more information on how QGIS handles project projection, please read the dedicated section at :ref:`label_projections`.

The crs :guilabel:`CRS` tab helps you set the coordinate reference system to use in this project. It can be:

  • checkbox :guilabel:`No CRS (or unknown/non-Earth projection)`: layers are drawn based on their raw coordinates
  • or an existing coordinate reference system that can be geographic, projected or user-defined. Layers added to the project are translated on-the-fly to this CRS in order to overlay them regardless their original CRS.

Transformations Properties

The transformation :guilabel:`Transformations` tab helps you control the layers reprojection settings by configuring the datum transformation preferences to apply in the current project. As usual, these override any corresponding global settings. See :ref:`datum_transformation` for more details.

Styles Properties

Under symbology :guilabel:`Styles` tab, you can configure symbols and colors inherent to the project, allowing to safely share the project among different machines.

img/project_styles.png

Styles tab

Default symbols

The :guilabel:`Default Symbols` group lets you control how new layers will be drawn in the project when they do not have an existing :file:`.qml` style defined. You can set :guilabel:`Marker`, :guilabel:`Line`, :guilabel:`Fill` to apply depending on the layer geometry type as well as default :guilabel:`Color Ramp` and :guilabel:`Text Format` (e.g., when enabling labeling). Any of these items can be reset using the :guilabel:`Clear` entry from the corresponding drop-down widget.

Symbol options

In the :guilabel:`Symbol options` group, you can:

Style Database

A style database in QGIS is a structured repository designed to store symbols, text formats, and other styling elements. It serves as a centralized location where you can organize and manage your symbology resources efficiently. You can create a dedicated style database for a specific client, housing symbols tailored to that client's need. This ensures a clean and organized approach, without cluttering the default style database. In multi-user environments, it's possible to store project-specific styles in a shared location. By linking a project to these styles, all users within the project gain access to common symbology, eliminating the need for manual import or updates to individual local style database. Storing symbols in a project file offers a practical solution, preventing users from overcrowding their global style database with project-specific symbology. This approach guarantees that other users working on the same project immediately have access to all the necessary symbology upon loading the project.

In the :guilabel:`Style Database` section you can choose to symbologyAdd :guilabel:`Add` or symbologyRemove :guilabel:`Remove` style database or you can newPage :guilabel:`Create new style database`. When you add or remove a style database in this section, the changes will be automatically reflected in the symbology :guilabel:`Symbology Properties`.

Colors properties

img/project_colors.png

Colors tab

In the colorSwatches :guilabel:`Colors` tab, you can select the :guilabel:`Color model`, i.e., whether selecting a color should by default be defined as RGB or CMYK. Any color defined in a different color model than the one specified here will be converted to this color model when exporting a layout.

Additionally, an option is available for selecting an :guilabel:`ICC Profile` which allows you to fileOpen :guilabel:`Load` a specific ICC profile that defines the color space for your project. After you load the ICC profile, you can choose to fileSave :guilabel:`Save ICC Profile` to a file on disk or to deleteSelected :guilabel:`Remove selected ICC Profile`. Once applied, QGIS will enforce the selected color model to ensure consistent color representation.

Note

Note that the :guilabel:`ICC Profile` option will only be visible if QGIS is built with Qt 6.8.0 or higher.

There is also an additional section where you can define specific colors for the running project. Like the :ref:`global colors <colors_options>`, you can:

Double-click a color in the list to tweak or replace it in the :ref:`Color Selector <color-selector>` dialog. You can also rename it by double-clicking in the :guilabel:`Label` column.

These colors are identified as :guilabel:`Project colors` and listed as part of :ref:`color widgets <color-selector>`.

Tip

Use project colors to quickly assign and update color widgets

Project colors can be referred to using their label and the color widgets they are used in are bound to them. This means that instead of repeatedly setting the same color for many properties and, to avoid a cumbersome update you can:

  1. Define the color as a project color
  2. Click the :ref:`data defined override widget <data_defined>` next to the color property you want to set
  3. Hover over the :guilabel:`Color` menu and select the project color. The property is then assigned the expression project_color('color_label') and the color widget reflects that color.
  4. Repeat steps 2 and 3 as much as needed
  5. Update the project color once and the change is reflected EVERYWHERE it's in use.

Data Sources Properties

In the openTable :guilabel:`Data Sources` tab, you can:

  • :guilabel:`Transaction mode`, defines how edits are sent to the data provider:

    • :guilabel:`Local Edit Buffer`: edits are buffered locally and sent to the provider when toggling layer editing mode or clicking :guilabel:`Save edits`.
    • :guilabel:`Automatic Transaction Groups`: on supported datasources (postgres and geopackage databases) the edit state of all tables that originate from the same database are synchronized and executed in a server side transaction. Also, instead of buffering edit changes locally, they are directly sent to a transaction in the database which gets committed when toggling layer editing mode or clicking :guilabel:`Save edits`.
    • :guilabel:`Buffered Transaction Groups`: all editable layers, disregarding from which provider, are toggled synchronously and all edits are saved in a local edit buffer. Saving changes is executed within a single transaction on all layers (per provider).

    Note that you can change this option only if no layer is being edited in the project.

  • unchecked :guilabel:`Evaluate default values on provider side`: When adding new features in a PostgreSQL table, fields with default value constraint are evaluated and populated at the form opening, and not at the commit moment. This means that instead of an expression like nextval('serial'), the field in the :guilabel:`Add Feature` form will display expected value (e.g., 25).

  • unchecked :guilabel:`Remember editable layer status between sessions`: makes sure that all layers that are editable in a project will be remembered as such when saving the project, as well as making sure that those layers are immediately made editable whenever the project is restored.

  • Configure the :guilabel:`Layers Capabilities`, i.e.:

    • Set (or disable) which layers are identifiable, i.e., will respond to the :ref:`identify tool <identify>`. By default, layers are set queryable.
    • Set whether a layer should appear as read-only, meaning that it can not be edited by the user, regardless of the data provider's capabilities. Although this is a weak protection, it remains a quick and handy configuration to avoid end-users modifying data when working with file-based layers.
    • Define which layers are searchable, i.e., could be queried using the :ref:`locator widget <locator_options>`. By default, layers are set searchable.
    • Define which layers are defined as required. Checked layers in this list are protected from inadvertent removal from the project.
    • Define which layers are private, i.e., hidden from the :guilabel:`Layers` panel. This is meant for accessory layers (basemap, join, lookups for value-relations, most probably aspatial layers, ...) that you still need in a project but you don't want them to pollute the legend tree and other layer selection tools. If set visible, they are still displayed in the map canvas and rendered in the print layout legend. Use the filterMap :menuselection:`Filter legend --> Show private layers` option in the :guilabel:`Layers` panel top toolbar to temporarily turned them on for any interaction.

    The :guilabel:`Layers Capabilities` table provides some convenient tools to:

  • Under the :guilabel:`Advanced Settings` group, you can select unchecked :guilabel:`Trust project when data source has no metadata`: To speed up project loading by skipping data checks. Useful in QGIS Server context or in projects with huge database views/materialized views. The extent of layers will be read from the QGIS project file (instead of data sources) and when using the PostgreSQL provider the primary key unicity will not be checked for views and materialized views.

img/project_datasources.png

Data Sources tab

Relations Properties

The relations :guilabel:`Relations` tab is used to define relations between layers. The relations can be of one to one, many to many or polymorphic type. They are defined in the project properties dialog. Once relations exist for a layer, a new user interface element in the form view (e.g., when identifying a feature and opening its form) will list the related entities. This provides a powerful way to express e.g., the inspection history on a length of pipeline or road segment. You can find out more about relations support in section :ref:`vector_relations`.

img/project_relations.png

Relations tab

Variables Properties

The expression :guilabel:`Variables` tab lists all the variables available at the project's level (which includes all global variables). Besides, it also allows the user to manage project-level variables. Click the symbologyAdd button to add a new custom project-level variable. Likewise, select a custom project-level variable from the list and click the symbologyRemove button to remove it. More information on variables usage in the General Tools :ref:`general_tools_variables` section.

Macros Properties

The action :guilabel:`Macros` tab is used to edit Python macros for projects. Currently, only three macros are available: openProject(), saveProject() and closeProject().

img/macro.png

Macro settings

QGIS Server Properties

The overlay :guilabel:`QGIS Server` tab allows you to configure your project in order to publish it online. Here you can define information about the QGIS Server WMS and WFS capabilities, extent and CRS restrictions. More information available in section :ref:`Creatingwmsfromproject` and subsequent.

img/project_qgis_server.png

QGIS Server settings

.. index:: Temporal; Project time range

Temporal Properties

The temporal :guilabel:`Temporal` tab is used to set the temporal range of your project, either by using manual :guilabel:`Start date` and :guilabel:`End date` inputs or by calculating it from the current project temporal layers. The project time range can then be used in the :guilabel:`Temporal controller panel` to manage the map canvas :ref:`temporal navigation <maptimecontrol>`.

img/project_temporal.png

Project Temporal tab

.. index:: Terrain; Elevation

Elevation Properties

The elevationscale :guilabel:`Elevation` tab helps you configure default settings for the terrain and elevation. When any new :ref:`3d map <label_3dmapview>` is created in the project, the map will default to using the same terrain settings as are defined for the project. The project elevation settings will also be respected by the :ref:`elevation profile <label_elevation_profile_view>` tool.

img/project_elevation.png

Project Elevation tab

.. index:: Sensors; Readings

Sensors Properties

The sensor :guilabel:`Sensors` tab is used to configure sensors and toggle their connection status. When active, sensors will passively collect data in the background and make available their latest data to expressions and python scripts.

img/project_sensors.png

Project Sensors tab

To add a new sensor, click on the symbologyAdd button. A settings sub-panel will open and allow you to configure:

  • the :guilabel:`Sensor name`: used to retrieve sensor values in expressions and python scripts;

  • the :guilabel:`Sensor type`: TCP, UDP, serial port, etc.; and

  • additional type-specific details (e.g., host name and port).

    For serial port sensors, comboboxes with the system's available serial ports and connection baud rate are available for their selection. A :guilabel:`Data frame delimiter` can be used to parse returned data. In case multiple data frames are found in the last chunk of data pushed by the serial port, all the data frames are returned. You can then use an expression to further split the returned sensor last data value into individual frames (e.g., using :ref:`string_to_array <expression_function_Arrays_string_to_array>` function).

img/project_sensors_configuration.png

Sensor Settings sub-panel

Once a sensor is configured, you can use the start Start button to connect the sensor. Once active, the last collected data will be displayed in the sensors table's :guilabel:`Last value` column.

.. index:: Customization

Customization

The :guilabel:`Customization` dialog lets you (de)activate almost every element in the QGIS user interface. This can be very useful if you want to provide your end-users with a 'light' version of QGIS, containing only the icons, menus or panels they need.

Note

Before your changes are applied, you need to restart QGIS.

img/customization.png

The Customization dialog

Ticking the checkbox :guilabel:`Enable customization` checkbox is the first step on the way to QGIS customization. This enables the toolbar and the widget panel from which you can uncheck and thus disable some GUI items.

The configurable item can be:

With select Switch to catching widgets in main application, you can click on an item in QGIS interface that you want to be hidden and QGIS automatically unchecks the corresponding entry in the Customization dialog. You can also use the :guilabel:`Search` box to find items by their name or label.

Once you setup your configuration, click :guilabel:`Apply` or :guilabel:`OK` to validate your changes. This configuration becomes the one used by default by QGIS at the next startup.

The modifications can also be saved in a .ini file using fileSave Save To File button. This is a handy way to share a common QGIS interface among multiple users. Just click on fileOpen Load from File from the destination computer in order to import the .ini file. You can also run :ref:`command line tools <custom_commandline>` and save various setups for different use cases as well.

Tip

Easily restore predefined QGIS

The initial QGIS GUI configuration can be restored by one of the methods below:

In most cases, you need to restart QGIS in order to have the change applied.

.. index:: Keyboard shortcuts

Keyboard shortcuts

QGIS provides default keyboard shortcuts for many features. You can find them in section :ref:`label_menubar`. Additionally, the menu option :menuselection:`Settings -->` keyboardShortcuts :menuselection:`Keyboard Shortcuts...` allows you to change the default keyboard shortcuts and add new ones to QGIS features.

img/shortcuts.png

Define shortcut options

Configuration is very simple. Use the search box at the top of the dialog to find a particular action, select it from the list and click on :

Proceed as above for any other tools you wish to customize. Once you have finished your configuration, simply :guilabel:`Close` the dialog to have your changes applied. You can also :guilabel:`Save` the changes either as an :file:`.XML` file with only the User Shortcuts or with all Shortcuts or as an :file:`.PDF` file with all Shortcuts and :guilabel:`Load` them into another QGIS installation.

.. index:: Command line options

Running QGIS with advanced settings

Command line and environment variables

We've seen that :ref:`launching QGIS <label_startingqgis>` is done as for any application on your OS. QGIS provides command line options for more advanced use cases (in some cases you can use an environment variable instead of the command line option). To get a list of the options, enter qgis --help on the command line, which returns:

QGIS is a user friendly Open Source Geographic Information System.
Usage: /usr/bin/qgis.bin [OPTION] [FILE]
  OPTION:
        [-v, --version]     display version information and exit
        [-s, --snapshot filename]   emit snapshot of loaded datasets to given file
        [-w, --width width] width of snapshot to emit
        [-h, --height height]       height of snapshot to emit
        [-l, --lang language]       use language for interface text (changes existing override)
        [-p, --project projectfile] load the given QGIS project
        [-e, --extent xmin,ymin,xmax,ymax]  set initial map extent
        [-n, --nologo]      hide splash screen
        [-V, --noversioncheck]      don't check for new version of QGIS at startup
        [-P, --noplugins]   don't restore plugins on startup
        [-B, --skipbadlayers]     don't prompt for missing layers
        [-C, --nocustomization]     don't apply GUI customization
        [-z, --customizationfile path]      use the given ini file as GUI customization
        [-g, --globalsettingsfile path]     use the given ini file as Global Settings (defaults)
        [-a, --authdbdirectory path] use the given directory for authentication database
        [-f, --code path]   run the given python file on load
        [-F, --py-args arguments]   arguments for python. These arguments will be available for each python execution via 'sys.argv' including the file specified by '--code'. All arguments till '--' are passed to python and ignored by QGIS.
        [-d, --defaultui]   start by resetting user ui settings to default
        [--hide-browser]        hide the browser widget
        [--dxf-export filename.dxf]     emit dxf output of loaded datasets to given file
        [--dxf-extent xmin,ymin,xmax,ymax]      set extent to export to dxf
        [--dxf-symbology-mode none|symbollayer|feature] symbology mode for dxf output
        [--dxf-scale-denom scale]       scale for dxf output
        [--dxf-encoding encoding]       encoding to use for dxf output
        [--dxf-map-theme maptheme]      map theme to use for dxf output
        [--take-screenshots output_path]        take screen shots for the user documentation
        [--screenshots-categories categories]   specify the categories of screenshot to be used (see QgsAppScreenShots::Categories).
        [--profile name]        load a named profile from the user's profiles folder.
        [-S, --profiles-path path]  path to store user profile folders. Will create profiles inside a {path}\profiles folder
        [--version-migration]   force the settings migration from older version if found
        [--openclprogramfolder]         path to the folder containing the sources for OpenCL programs.
        [--help]                this text
        [--]            treat all following arguments as FILEs

  FILE:
    Files specified on the command line can include rasters,
    vectors, and QGIS project files (.qgs and .qgz):
     1. Rasters - supported formats include GeoTiff, DEM
        and others supported by GDAL
     2. Vectors - supported formats include ESRI Shapefiles
        and others supported by OGR and PostgreSQL layers using
        the PostGIS extension

Tip

Example Using command line arguments

You can start QGIS by specifying one or more data files on the command line. For example, assuming you are in the :file:`qgis_sample_data` directory, you could start QGIS with a vector layer and a raster file set to load on startup using the following command: qgis ./raster/landcover.img ./gml/lakes.gml

--version

This option returns QGIS version information.

--snapshot

This option allows you to create a snapshot in PNG format from the current view. This comes in handy when you have many projects and want to generate snapshots from your data, or when you need to create snapshots of the same project with updated data.

Currently, it generates a PNG file with 800x600 pixels. The size can be adjusted using the --width and --height arguments. The filename can be added after --snapshot. For example:

qgis --snapshot my_image.png --width 1000 --height 600 --project my_project.qgs

--width

This option returns the width of the snapshot to be emitted (used with --snapshot).

--height

This option returns the height of the snapshot to be emitted (used with --snapshot).

--lang

Based on your locale, QGIS selects the correct localization. If you would like to change your language, you can specify a language code. For example, qgis --lang it starts QGIS in Italian localization.

--project

Starting QGIS with an existing project file is also possible. Just add the command line option --project followed by your project name and QGIS will open with all layers in the given file loaded.

--extent

To start with a specific map extent use this option. You need to add the bounding box of your extent in the following order separated by a comma:

--extent xmin,ymin,xmax,ymax

This option probably makes more sense when paired with the --project option to open a specific project at the desired extent.

--nologo

This option hides the splash screen when you start QGIS.

--noversioncheck

Skip searching for a new version of QGIS at startup.

--noplugins

If you have trouble at start-up with plugins, you can avoid loading them at start-up with this option. They will still be available from the Plugins Manager afterwards.

--nocustomization

Using this option, any existing :ref:`GUI customization <sec_customization>` will not be applied at startup. This means that any hidden buttons, menu items, toolbars, and so on, will show up on QGIS start up. This is not a permanent change. The customization will be applied again if QGIS is launched without this option.

This option is useful for temporarily allowing access to tools that have been removed by customization.

--skipbadlayers

Using this option, you can avoid QGIS prompting the :guilabel:`Handle Unavailable Layers` dialog at startup. The project file is loaded, with missing layers kept as unavailable. More details on the topic at :ref:`handle_broken_paths`.

--customizationfile

Using this option, you can define a UI customization file, that will be used at startup.

--globalsettingsfile

The equivalent environment variable is QGIS_GLOBAL_SETTINGS_FILE.

Using this option, you can specify the path for a Global Settings file (.ini), also known as the Default Settings. The settings in the specified file replace the original inline default ones, but the user profiles' settings will be set on top of those.

QGIS looks for the default global settings file in the following order and only the first found file will be used:

Presently, there's no way to specify a file to write settings to; therefore, you can create a copy of an original settings file, rename, and adapt it.

Setting the :file:`qgis_global_setting.ini` file path to a network shared folder, allows a system administrator to change global settings and defaults in several machines by only editing one file.

--authdbdirectory

This option is similar to --globalsettingsfile, but defines the path to the directory where the authentication database will be stored and loaded.

--code

This option can be used to run a given python file directly after QGIS has started.

For example, when you have a python file named :file:`load_alaska.py` with following content:

from qgis.utils import iface
raster_file = "/home/gisadmin/Documents/qgis_sample_data/raster/landcover.img"
layer_name = "Alaska"
iface.addRasterLayer(raster_file, layer_name)

Assuming you are in the directory where the file :file:`load_alaska.py` is located, you can start QGIS, load the raster file :file:`landcover.img` and give the layer the name 'Alaska' using the following command:

qgis --code load_alaska.py

--py-args

This option allows to pass arguments to the script provided via the :ref:`--code <code_commandline>` parameter and more generally to each python execution. After --py-args, it is not possible to pass any other parameter than :ref:`-- <file_commandline>` to QGIS. All arguments after --py-args till -- are passed over to the python interpreter and ignored by QGIS.

qgis --code /home/user/test.py --py-args --specialScriptArguments "a text arg" 'and another arg' -- layer1 layer2

In the above code, :file:`test.py` will have this content in sys.argv: ['/home/user/test.py', '--specialScriptArguments', 'a text arg', 'and another arg']. layer1 and layer2 will be normally handled by QGIS as layers to load.

--defaultui

On load, permanently resets the user interface (UI) to the default settings. This option will restore the panels and toolbars visibility, position, and size. Unless it's changed again, the default UI settings will be used in the following sessions.

Notice that this option doesn't have any effect on :ref:`GUI customization <sec_customization>`. Items hidden by GUI customization (e.g., the status bar) will remain hidden even using the --defaultui option. See also the --nocustomization option.

--hide-browser

On load, hides the :guilabel:`Browser` panel from the user interface. The panel can be enabled by right-clicking a space in the toolbars or using the :menuselection:`View --> Panels` (:menuselection:`Settings --> Panels` in kde Linux KDE).

Unless it's enabled again, the Browser panel will remain hidden in the following sessions.

--dxf-*

These options can be used to export a QGIS project into a DXF file. Several options are available:

  • --dxf-export: the DXF filename into which to export the layers;
  • --dxf-extent: the extent of the final DXF file;
  • --dxf-symbology-mode: several values can be used here: none (no symbology), symbollayer (Symbol layer symbology), feature (feature symbology);
  • --dxf-scale-denom: the scale denominator of the symbology;
  • --dxf-encoding: the file encoding;
  • --dxf-map-theme: choose a :ref:`map theme <map_themes>` from the layer tree configuration.

--take-screenshots

Takes screenshots for the user documentation. Can be used together with --screenshots-categories to filter which categories/sections of the documentation screenshots should be created (see QgsAppScreenShots::Categories).

--profile

Loads QGIS using a specific profile from the user's profile folder. If the named profile doesn't exist, it will be created. This option takes precedence over :ref:`user profile startup setting <user_profile_setting>`.

--profiles-path

With this option, you can choose a path to load and save the profiles (user settings). It creates profiles inside a {path}\profiles folder, which includes settings, installed plugins, processing models and scripts, and so on.

This option allows you to, for instance, carry all your plugins and settings in a flash drive, or, for example, share the settings between different computers using a file sharing service.

The equivalent environment variable is QGIS_CUSTOM_CONFIG_PATH.

--version-migration

If settings from an older version are found (e.g., the .qgis2 folder from QGIS 2.18), this option will import them into the default QGIS profile.

--openclprogramfolder

Using this option, you can specify an alternative path for your OpenCL programs. This is useful for developers while testing new versions of the programs without needing to replace the existing ones.

The equivalent environment variable is QGIS_OPENCL_PROGRAM_FOLDER.

--

This option allows to pass following arguments as files to open in QGIS. They can be supported rasters or vectors files, QGIS layer definition files or project files.

qgis -- /home/user/project.qgs /home/user/path_to_data/layer1.gpkg

The above code will start QGIS, open the :file:`project` file and load :file:`layer1` in it.

Deploying QGIS within an organization

If you need to deploy QGIS within an organization with a custom configuration file, first you need to copy/paste the content of the default settings file located in :file:`your_QGIS_package_path/resources/qgis_global_settings.ini`. This file already contains some default sections identified by a block starting with []. We recommend that you keep these defaults values and add your own sections at the bottom of the file. If a section is duplicated in the file, QGIS will take the last one from top to bottom.

You can change allowVersionCheck=false to disable the QGIS version check.

If you do not want to display the migration window after a fresh install, you need the following section:

[migration]
fileVersion=2
settings=true

If you want to add a custom variable in the global scope:

[variables]
organisation="Your organization"

A lot of settings can be set using the :file:`.INI` file such as WMS/WMTS, PostgreSQL connections, proxy settings, maptips, default values for algorithms parameters… For example, if you want to configure organization wide default values for some algorithms it would be handy if you could configure it in the prepared ini-file for all users. If the users then open the toolbox to execute an algorithm, the default values will be there. To set the default value, e.g., for GRID_SIZE parameter for the native:intersection algorithm, you could write the following into the :file:`.INI` file:

[Processing]
DefaultGuiParam\native%3Aintersection\GRID_SIZE=0.01

Not all settings can be prepared from QGIS GUI, but to discover the possibilities of the settings :file:`.INI` file, we suggest that you set the config you would like in QGIS Desktop and then search for it in your :file:`.INI` file located in your profile using a text editor.

Finally, you need to set the environment variable QGIS_GLOBAL_SETTINGS_FILE to the path of your customized file.

In addition, you can also deploy files such as Python macros, color palettes, layout templates, project templates… either in the QGIS system directory or in the QGIS user profile.