Qgis Knowledge Patch

QGIS Knowledge Patch

Use this skill when implementing, reviewing, migrating, or troubleshooting QGIS desktop, Server, Processing, provider, or PyQGIS work where recent behavior can change the answer.

How to use this patch

1. Identify the QGIS version and, for provider-backed features, the packaged GDAL, PDAL, wrench, GEOS, or SFCGAL versions.
2. Read only the topic references needed for the task.
3. Apply guidance introduced no later than the project's QGIS version.
4. Prefer the installed build's capabilities, project files, and runtime behavior when they differ from this guidance.
5. Treat UI defaults separately from API availability and provider-library prerequisites.

Reference index

Breaking changes and migration

Advertise QGIS 4 compatibility with version bounds

For plugin repositories, use qgisMinimumVersion and optional qgisMaximumVersion. With no maximum, compatibility is assumed only through the end of the minimum version's major line. A plugin retaining QGIS 3.22 support while advertising QGIS 4 support can use:

[general]
qgisMinimumVersion=3.22
qgisMaximumVersion=4.99

The QGIS 4 Ready list accepts a plugin when either bound is at least 4.0. Remove supportsQt6=True; it is no longer recognized. Before widening the range, replace Qt 5-only APIs and direct PyQt5 imports, preferably using qgis.PyQt, test on QGIS 4, and use the repository's pyqgis4-checker report. See Plugins, projects, and migration.

Redirect settings and deployment automation

QGIS 4.2 uses settings separate from QGIS 3. Its first startup makes a one-time, lossless copy of the loaded QGIS 3 profile, but later edits do not synchronize. Installation, profile, backup, and enterprise deployment scripts must target the QGIS 4 location.

Update the QGIS Server OAPIF route

Since 4.0, the default OAPIF root is /ogcapi, replacing /wfs3. Set QGIS_SERVER_API_WFS3_ROOT_PATH when a deployment needs another path, and update reverse-proxy routes, clients, and tests together.

Replace deprecated hub-distance algorithms

Since 4.0, the C++ Hub Distance algorithm replaces Distance to Nearest Hub (Points) and Distance to Nearest Hub (Line to Hub). It provides both optional outputs; migrate models and automation away from the two deprecated IDs.

Account for changed legend defaults

Since 4.0, layout legends use All Project Layers, Visible Layers, or Manual Layer Selection instead of the former Auto update checkbox. New legends default to Visible Layers. This follows layer-tree visibility and changes but does not filter by map extent; a global layout option restores the old default.

Capability gates

Check runtime library versions before exposing these operations:

• COG export controls and GDAL Data Identification require GDAL 3.13 or later (4.0).
• GeoPackage field-domain updates and deletion require GDAL 3.12 or later (4.0).
• M3C2 point-cloud comparison requires a build with PDAL later than 2.10 (4.0).
• Export to Raster (TIN) maximum-edge filtering requires PDAL 2.6+ and wrench 1.2.2+ (4.0).
• Approximate Medial Axis extendToEdges requires SFCGAL 2.3 (4.2).
• Some raster, point-cloud, 3D Tiles, I3S, and provider features remain conditional on the providers compiled into the installed QGIS build.

High-value desktop behavior

Choose the right layout-legend mode

• All Project Layers tracks the whole project.
• Visible Layers tracks visibility, order, and layer-tree changes.
• Manual Layer Selection keeps an explicit list.
• Per-layer automatic legend inclusion is enabled by default for vector, raster, mesh, and point-cloud layers (4.0).

Keep temporary outputs named

Processing outputs can remain temporary while using a user-selected layer name (4.0). The memory-chip icon still identifies them as temporary; naming a result does not persist it.

Preserve raw provider values when copying

Attribute tables and Identify Results can copy literal provider values rather than represented values affected by locale formatting, expressions, or display relations (4.0). Choose the raw action for round-tripping or exact comparisons.

Use cumulative temporal raster rendering

Raster layers in represent-temporal-values mode can accumulate pixels over time (4.0), matching cumulative vector animation behavior. Enable it when raster and vector frames must remain temporally aligned.

Use isolated label-collision controls

• Cross-layer margins reserve space around a label (3.44).
• Duplicate prevention suppresses case-sensitive matching text within a minimum distance across all layers (3.44).
• Curved labels can ignore spaces and tabs during collision tests; this is off by default and applies only to curved placement (4.0).

High-value Processing behavior

Distinguish COG from ordinary GeoTIFF

When creating Cloud Optimized GeoTIFF output, pass -of COG explicitly (4.0). The .tif or .tiff extension cannot distinguish the COG and GTiff drivers. With GDAL 3.13+, export dialogs can also request optimization and pyramids.

Preserve provenance when merging vectors

Merge Vector Layers can add source layer and path attributes (3.42). The option is enabled by default for backward compatibility; disable it only when the output schema must exclude provenance.

Understand raster-rank NoData behavior

Raster rank uses positive ranks from the low end and negative ranks from the high end: for [10, 20, 30, 40], 2 gives 20 and -2 gives 30 (3.44). The default ignores NoData unless the requested rank is unavailable; the alternate mode propagates NoData when any input cell is NoData.

Keep WMS extraction scale-aware

Clip Raster by Extent and Clip Raster by Mask Layer can request WMS input at a reference scale and service resolution (4.0). The default service resolution is 96 DPI. Use this when scale-dependent remote rendering must survive a clip.

High-value APIs

Geometry and dataframe conversion

• QgsGeometry.as_numpy() preserves Z and M dimensionality as XYZ, XYM, or XYZM arrays (3.42).
• QgsGeos is directly available to PyQGIS for GEOS-specific operations not exposed by QgsGeometryEngine (3.42).
• QgsGeometry.area3D() computes polygonal surface area and returns zero for points and lines (4.0).
• QgsVectorLayer.as_geopandas() creates a GeoPandas dataframe when GeoPandas is installed (4.0).

Time-zone semantics

convert_timezone preserves the instant and changes its local representation; set_timezone replaces the zone without changing the date or time components (4.0). Use timezone_from_id, timezone_id, and get_timezone for IANA-zone creation and inspection.

Point-cloud color expressions

Point-cloud renderers can modify @point_color with point attributes (4.2). Arithmetic is channel-by-channel RGBA. Multiplication permits the color on either side, while other operators require it on the left, for example:

@point_color * (@intensity / 65535)

Server operational checks

• QGIS_SERVER_PROJECT_CACHE_SIZE controls server project-cache QCache cost (3.44).
• QGIS_SERVER_RETRY_BAD_LAYERS=true retests previously bad layers on every request and restores them after dependencies recover (4.0).
• HTML GetFeatureInfo can use only the layer maptip via the project setting corresponding to WITH_MAPTIP=HTML_FI_ONLY_MAPTIP (4.0).
• WMS highlight-label frames accept background, outline color, outline width, and size vendor parameters, optionally scoped per map (4.2).
• QGIS Server can answer mesh GetFeatureInfo (4.0) and export FlatGeobuf from OGC API Features (4.2).

Verification checklist

• Confirm the installed QGIS and provider-library versions.
• Check defaults separately for newly created and existing projects.
• For plugin migration, test imports, metadata bounds, UI behavior, and package validation on QGIS 4.
• For Server changes, test direct requests and proxy-routed public URLs.
• For Processing, inspect output schema, NoData handling, CRS, temporary versus persisted status, and conditional outputs.
• For 3D or point clouds, verify both renderer support and data locality before enabling editing.