QGIS Documentation

1. Project Overview & Quickstart (qgis/QGIS) Copy Chapter

QGIS is a full-featured, user-friendly, free-and-open-source (FOSS) geographical information system (GIS) that runs on Unix platforms, Windows, and MacOS.

• Features
  • 1. Flexible and powerful spatial data management
  • 2. Beautiful cartography
  • 3. Advanced and robust geospatial analysis
  • 4. Powerful customization and extensibility
  • 5. QGIS Server
• Under the hood
  • Versions and release cycle
  • Free and Open Source
• Installing and using QGIS
  • Documentation
  • Help and support channels
• Get involved with the community

Features Copy Chapter

1. Flexible and powerful spatial data management Copy Section

• Support for raster, vector, mesh, and point cloud data in a range of industry-standard formats
  • Raster formats include: GeoPackage, GeoTIFF, GRASS, ArcInfo binary and ASCII grids, ERDAS Imagine SDTS, WMS, WCS, PostgreSQL/PostGIS, and other GDAL supported formats.
  • Vector formats include: GeoPackage, ESRI shapefiles, GRASS, SpatiaLite, PostgreSQL/PostGIS, MSSQL, Oracle, WFS, Vector Tiles and other OGR supported formats.
  • Mesh formats include: NetCDF, GRIB, 2DM, and other MDAL supported formats.
  • Point-cloud format: LAS/LAZ and EPT datasets.
• Data abstraction framework, with local files, spatial databases (PostGIS, SpatiaLite, SQL Server, Oracle, SAP HANA), and web services (WMS, WCS, WFS, ArcGIS REST) all accessed through a unified data model and browser interface, and as flexible layers in user-created projects
• Spatial data creation via visual and numerical digitizing and editing, as well as georeferencing of raster and vector data
• On-the-fly reprojection between coordinate reference systems (CRS)
• Nominatim (OpenStreetMap) geocoder access
• Temporal support

Example: Temporal animation

Example: 3D map view

2. Beautiful cartography Copy Section

• Large variety of rendering options in 2D and 3D
• Fine control over symbology, labeling, legends and additional graphical elements for beautifully rendered maps
• Respect for embedded styling in many spatial data sources (e.g. KML and TAB files, Mapbox-GL styled vector tiles)
• In particular, near-complete replication (and significant extension) of symbology options that are available in proprietary software by ESRI
• Advanced styling using data-defined overrides, blending modes, and draw effects
• 500+ built-in color ramps (cpt-city, ColorBrewer, etc.)
• Create and update maps with specified scale, extent, style, and decorations via saved layouts
• Generate multiple maps (and reports) automatically using QGIS Atlas and QGIS Reports
• Display and export elevation profile plots with flexible symbology
• Flexible output direct to printer, or as image (raster), PDF, or SVG for further customization
• On-the-fly rendering enhancements using geometry generators (e.g. create and style new geometries from existing features)
• Preview modes for inclusive map making (e.g. monochrome, color blindness)

Example: Map of Bogota, Colombia in the style of Starry Starry Night, by Andrés Felipe Lancheros Sánchez

For more maps created with QGIS, visit the following pages:

• Amazing maps created using QGIS

• Map Gallery on QGIS Hub

• QGIS Map Showcase Flickr Group.

3. Advanced and robust geospatial analysis Copy Section

• Powerful processing framework with 200+ native processing algorithms
• Access to 1000+ processing algorithms via providers such as GDAL, SAGA, GRASS, OrfeoToolbox, as well as custom models and processing scripts
• Geospatial database engine (filters, joins, relations, forms, etc.), as close to datasource- and format-independent as possible
• Immediate visualization of geospatial query and geoprocessing results
• Model designer and batch processing

Example: Travel isochrones

Example: Model designer

4. Powerful customization and extensibility Copy Section

• Fully customizable user experience, including user interface and application settings that cater to power-users and beginners alike
• Rich expression engine for maximum flexibility in visualization and processing
• Broad and varied plugin ecosystem that includes data connectors, digitizing aids, advanced analysis and charting tools,
  in-the-field data capture, conversion of ESRI style files, etc.
• Style manager for creating, storing, and managing styles
• QGIS style hub for easy sharing of styles
• Python and C++ API for standalone (headless) applications as well as in-application comprehensive scripting (PyQGIS)

Example: Style manager

Example: Plugins

5. QGIS Server Copy Section

Headless map server -- running on Linux, macOS, Windows, or in a docker container -- that shares the same code base as QGIS.

• Industry-standard protocols (WMS, WFS, WFS3/OGC API for Features and WCS) allow plug-n-play with any software stack
• Works with any web server (Apache, nginx, etc) or standalone
• All beautiful QGIS cartography is supported with best-in-class support for printing
• Fully customizable with Python scripting support

Example: QGIS server WMS response

Example: QGIS server WFS response

Under the hood Copy Chapter

QGIS is developed using the Qt toolkit and C++, since 2002, and has a pleasing, easy to use graphical
user interface with multilingual support. It is maintained by an active developer team and supported by vibrant
community of GIS professionals and enthusiasts as well as geospatial data publishers and end-users.

Versions and release cycle Copy Section

QGIS development and releases follow a time based schedule/roadmap. There are three main branches of QGIS that users can install. These are the Long Term Release (LTR) branch, the Latest Release (LR) branch, and the Development (Nightly) branch.

Every month, there is a Point Release that provides bug-fixes to the LTR and LR.

Free and Open Source Copy Section

QGIS is released under the GNU Public License (GPL) Version 2 or any later version.
Developing QGIS under this license means that you can (if you want to) inspect
and modify the source code and guarantees that you, our happy user will always
have access to a GIS program that is free of cost and can be freely
modified.

QGIS is part of the Open-Source Geospatial Foundation (OSGeo), offering a range of complementary open-source GIS software projects.

Installing and using QGIS Copy Chapter

Precompiled binaries for QGIS are available at the QGIS.org download page.
Please follow the installation instructions carefully.

The building guide can be used to get started with building QGIS from source.

For installation of QGIS Server, see its getting started documentation.

Documentation Copy Section

A range of documentation is available. This includes:

• Training Manual
• QGIS User Guide
• QGIS Server Guide
• Visual Changelog
• Documentation Guidelines
• QGIS Python (PyQGIS) Cookbook
• QGIS Python (PyQGIS) API
• QGIS C++ API
• Developers Guide

Help and support channels Copy Section

There are several channels where you can find help and support for QGIS:

• Using the QGIS community site
• Joining the qgis-users mailing list
• Chatting with other users real-time. Please wait around for a response to your question as many folks on the channel are doing other things and it may take a while for them to notice your question. The following paths all take you to the same chat room:
  • Using an IRC client and joining the
    #qgis channel on irc.libera.chat.
  • Using a Matrix client and joining the #qgis:osgeo.org room.
• At the GIS stackexchange or r/QGIS reddit, which are not maintained by the QGIS team, but where the QGIS and broader GIS community provides lots of advice
• Other support channels

Get involved with the community Copy Chapter

Contribution guidelines for this project

2. Official Technical Reference & Guides (qgis/QGIS-website) Copy Chapter

🌐 QGIS Website [](https://blog.qgis.org/2025/02/08/qgis-recognized-as-digital-public-good/)

👋 Welcome to QGIS.org! Copy Chapter

This repository hosts the source code for the official QGIS Project website:
🌍 https://qgis.org

Here you'll find everything you need to build, develop, and contribute to the QGIS website.

⚠️ Note on Subdomain Websites Copy Section

This repository is only for the main QGIS website (qgis.org).

If you are looking for the source code or want to contribute to QGIS subdomain websites, please visit their respective repositories below.
Each subdomain has its own codebase and contribution process:

• plugins.qgis.org (GitHub: QGIS-Plugins-Website) – QGIS Plugins Repository
• hub.qgis.org (GitHub: QGIS-Hub-Website) – QGIS Resources Hub
• feed.qgis.org (GitHub: qgis-feed) – QGIS Feed Manager
• planet.qgis.org (GitHub: QGIS-Planet-Website) – QGIS Planet Blog Aggregator
• members.qgis.org (GitHub: QGIS-Members-Website) – QGIS Sustaining Members Portal
• certification.qgis.org (GitHub: QGIS-Certification-Website) – QGIS Certification Programme Platform
• changelog.qgis.org (GitHub: QGIS-Changelog-Website) – QGIS Changelog Manager
• conference.qgis.org (GitHub: QGIS-UC-Website) – QGIS User Conference Website

📖 Table of Contents

Table of Contents

1. 🚀 Project Overview


2. 🚥 QA Status


3. 📜 License


4. 📂 Folder Structure


5. 🤖 Using 'AI' (Large Language Models)


6. 🌍 Localization & Build Docs


7. 🛠️ Scripts Overview


8. 🧊 Using the Nix Shell


9. ✨ Contributing


10. 🙋 Have Questions?


11. 🧑‍💻👩‍💻 Contributors

🚀 Project Overview Copy Chapter

🌍 Localization & Build Docs Copy Chapter

• Internationalization and translation workflow: see I18N.md
• Development and production build guide (including incremental per-language builds and media dedup): see DEVELOPMENT.md
• Content authoring standards for i18n: use shortcode params with spaces around =, keep shortcode closing >}} on the same line, and do not use inline HTML in markdown files. See I18N.md and CONTRIBUTING.md.

🚥 QA Status Copy Chapter

🪪 Badges Copy Section

⭐️ Project Stars Copy Section

📜 License Copy Chapter

This project is licensed under the MIT License. See the LICENSE file for details.

📂 Folder Structure Copy Chapter

QGIS-Website/
  ├── 🖼️  assets/           # Mainly used to store the schedule.csv file
  ├── ⚙️  config/           # Hugo configuration files
  ├── 📄  content/          # Markdown content files (pages, posts)
  ├── 🗄️  data/             # Data files (YAML, JSON, TOML) for site variables
  ├── 📚  docs/             # Project documentation
  ├── 🖼️  img/              # Images files used by this README
  ├── 🧩  layouts/          # Hugo templates and partials
  ├── 🧪  playwright/       # Playwright end-to-end test scripts
  ├── 📦  public/           # Generated site output (after `hugo` build)
  ├── 🗂️  resources/        # Hugo-generated resources (e.g., minified assets)
  ├── 🛠️  scripts/          # Utility scripts for development/maintenance/harvesting
  ├── 💻  source/           # Mainly used to store the qugsneews.atom file
  ├── 📄  static/           # Static files served as-is (e.g., favicon, robots.txt)
  ├── 🎨  themes/           # Hugo themes
  ├── ⚙️  config.toml       # Main Hugo configuration file
  ├── 🤝  CONTRIBUTING.md   # Contribution guidelines
  ├── 🐍  fetch_feeds.py*   # Script to get sustaining members and other feeds to update our web site
  ├── 📜  LICENSE           # Project license
  ├── ⚙️  Makefile          # Build/Deployment automation commands
  ├── 📖  README.md         # Project overview and instructions
  ├── 📋  REQUIREMENTS.txt  # Python dependencies (pip)
  ├── 🐚  flake.nix         # Nix flake (development environment)
  └── 💡  vscode.sh*        # VSCode helper script for the Nix development environment

🤖 Using 'AI' (Large Language Models) Copy Chapter

We are fine with using LLM's and Generative Machine Learning to act as general assistants, but the following three guidelines should be followed:

1. Repeatability: Although we understand that repeatability is not possible generally, whenever you are verbatim using LLM or Generative Machine Learning outputs in this project, you must also provide the prompt that you used to generate the resource.
2. Declaration: Sharing the prompt above is implicit declaration that a machine learning assistant was used. If it is not obvious that a piece of work was generated, include the robot (🤖) icon next to a code snippet or text snippet.
3. Validation: Outputs generated by a virtual assistant should always be validated by a human and you, as contributor, take ultimate responsibility for the correct functionality of any code and the correct expression in any text or media you submit to this project.

🛠️ Scripts Overview Copy Chapter

The scripts/ folder contains utility scripts to assist with data loading, and project maintenance. Below is a summary of each script:

✏️ Note: Run each script from the project root. Some scripts may require environment variables or configuration—see comments within each script for usage details.

🧊 Using the Nix Shell Copy Chapter

Please refer to the Nix section in CONTRIBUTING.md.

✨ Contributing Copy Chapter

We welcome contributions! Please read the CONTRIBUTING.md for guidelines on how to get started.

🙋 Have Questions? Copy Chapter

Have questions or feedback? Feel free to open an issue or submit a Pull Request!

🧑‍💻👩‍💻 Contributors Copy Chapter

• Tim Sutton – Original author and lead maintainer of the QGIS Website project
• Kontur Team – Responsible for the design and development of the current website version
• Lova Andriarimalala – Core developer and ongoing maintainer
• QGIS Contributors – See the full list of amazing contributors who have helped make this website possible.

• Hugo Language and Syntax Support
• Color Highlight

Clone the repo:

git clone https://github.com/qgis/QGIS-Website.git

Run the site:

Press Ctl-Shift-D then choose the following runner:

'Run dev using locally installed Hugo'

the click the green triangle next to the runner to start it.

Once the site is running, you can open it at:

http://localhost:1313

The site will automatically refresh any page you have open if you edit it and save your work. Magical eh?

Run in other IDEs Copy Chapter

Use an appropriate Hugo plugin for your IDE, or run Hugo from the command line:

hugo server

You can then visit the hot-reloaded site in your browser at http://localhost:1313/

Running Playwright End to End (e2e) Tests Copy Chapter

Test files are located in playwright/ci-test/tests.

These tests exist to make sure code changes to this repository do not break how the site currently functions.
They are intended to run on each commit to verify the site is working in the expected order.

Run tests with VSCode Copy Section

Requirements: NodeJS v18+

1. Install playwright: If you haven't already installed Playwright, you can do so by running the following commands in playwright/ci-test directory.

cd playwright/ci-test
npm install

2. Install playwright browsers:

npx playwright install --with-deps chromium

3. Install the extension Playwright Test for VSCode: This extension provides a seamless integration of Playwright testing into VSCode.

4. Open the Testing Tab: In VSCode, click on the Testing icon in the Activity Bar on the side of the window. This will open the Testing tab.

5. Run Playwright Tests from the Testing Tab:

• In the Testing tab, you should see your Playwright tests listed. If not, ensure the browser is checked under Playwright > Project menu.
• Click on the refresh button in the Testing tab to reload the tests.
• You can run individual tests by clicking the play button next to the test name.
• You can also run all tests by clicking the play button at the top of the Testing tab.

6. Debugging Tests:

• You can debug individual tests by clicking the debug icon (a small bug with a play button) next to the test name.
• Make sure to set breakpoints in your test files before running the debugger.

Run tests with CLI Copy Section

By default, this will run in headless mode just as it is in CI.

./run-tests.sh

NOTE: To run it in UI mode, add the --ui tag to the script.

$PLAYWRIGHT \
    test \
    --ui \
    --project chromium

Read more on testing here.

Running as github action Copy Section

There is a github action that will run the tests automatically on PR submission, merge.

See .github/workflows/playwright-e2e.yml

Content Harvesting Copy Chapter

You can harvest data from various feeds using the fetch_feeds.py script. By default
flickr harvesting is disabled in this script so run it manually and review the content
to see if it is suitable for publication on our site.

./fetch_feeds.py --flickr=yes

Flickr parsing creates new files and md pages with param draft: true. It can be changed to false after manual verification. The script will not overwrite the changes. Pictures with draft: false will appear on /project/overview/maps/ and /project/overview/screenshots/.

This script is run nightly as a github action (see .github/workflows/update-feeds.yml).

Search Functionality Copy Chapter

The search functionality uses both FuseJS and MarkJS.

The search functionality code is based on this Blog Post and GitHub Gist by Eddie Webb.

Content folders need to be excluded from search, by making them headless bundles - which we have done for the sustaining member and flagship user folders in content/. To make other content folders which are not rendered and included in search results, add an index.md file with the following content: headless = true.

Referencing URLs in templates Copy Chapter

The site needs to work in production, where the links of the site are all below the root URL, and in staging, where the site is deployed to GitHub pages in a subpath. To ensure both deployment strategies work, please use the following method of constructing URLs in templates.

<a class="button is-primary" href="{{ "donate/" | absURL }}">

Note: We do not use a leading slash, only an ending slash.

Styles (SASS/CSS) Copy Chapter

SASS for most components is stored in themes/qgis-website-theme/assets/sass/bulma/components/

Some common styles are places in themes/qgis-website-theme/assets/sass/style.sass - this file is compiled as hugo template, hence has access to config.toml variables and hugo macroses

Also some bulma theme overrides are placed in themes/qgis-website-theme/assets/css/custom.css

📁 File naming conventions Copy Chapter

• Separate words in file names with hyphens e.g. windows-download.md
• Avoid abbreviations in the words of your files
• Write file names in lower case only
• No spaces in file names

🤝 Contributing to this project Copy Chapter

We welcome your contributions! All contributors are expected to sign a contributor license agreement (CLA) which you can see here. This process is automatically enabled when you create your first pull request via https://cla-assistant.io/.

💮 Changing the templates Copy Chapter

🏠 Editing the landing (home) page Copy Chapter

The layout of the landing page is themes/qgis-website-theme/layouts/index.html: the main page has many diverse blocks, that are not used anywhere else, hence its content is mostly in the partials.

The content/_index.md contains the front matter of the page and the contents for the feature shortcodes. Just edit whatever you like there. The blocks shortcodes are described here

📃 Adding a top level page Copy Chapter

Create the content Copy Section

Content pages are stored in the content folder. The top level documents there will be rendered with the top level page theming.

For example to add an about page, create content/about.md

The page will be accessible then at /about/

🖼️ Referencing Images and Media Copy Section

Place images and media in static/img. Everything in static is referenced
from the top level of the site e.g. static/img/foo.png would be referenced in
markdown as /img/foo.png.

📦 Blocks Shortcodes Copy Chapter

The site uses a number of shortcodes to create reusable blocks of content. These are defined in the themes/qgis-website-theme/layouts/shortcodes/ folder.

The shortcodes with screenshots are described here

Reusable header web component Copy Section

TODO

Sidebar Copy Section

Sidebar is implemented in themes/qgis-website-theme/layouts/partials/sidebar.html

Items are retrieved from config.toml under [menu] section. weight parameter defines the order of the item.

To enable sidebar on the content page, use the following template:

---
type: "page"
...
sidebar: true
---
{{< content-start  >}}

... add content here ...

{{< content-end  >}}

LT/LTR release variables Copy Section

Script for parsing release schedule from the google spreadsheet is scripts/update-schedule.py. It creates data/conf.json with variables that can be used later in md/html.

Script for harvesting the visualchangelog from changelog.qgis.org is scripts/changelog_harvest.py. It will create/update a visual-changelogs at content/project/visual-changelogs based on the data at data/conf.json.

Usage:

$ ./scripts/changelog_harvest.py

# For a specific version
$ ./scripts/changelog_harvest.py --version 3.34 --release 21.06.2024

# Resizing the images for existing changelog
$ ./scripts/changelog_harvest.py --version 3.34 --release 21.06.2024 --use_existing

Example usage in md:

Here you will simply install the latest stable QGIS ({{< param "version" >}}.x {{< param "codename" >}})

To include param as link, use param-link shortcode: it correctly renders as md link, and not as plain text

Electronic document: {{< param-link "userguidecite" >}}

Example usage in HTML:

to use params inside shortcode or partial, use wrapper:

{{ with index .Site.Data.conf }}
...
<a
	class="button is-primary1 mb-3"
	href="{{ .ltr_msi }}"
	onclick="thanks(this)"
	download
>Long Term Version for Windows ({{ .ltrversion }} {{ .ltrnote }})</a>

{{ end }}

Example usage as shortcode param:

tricky part: shortcodes can't be used as other shortcodes' params. So you need to make replacement in the outer shortcode: "tabs.html" make a replacement of |ltrversion| and |version| to the values from config.

{{< tabs tab1="QGIS |ltrversion|" tab2="QGIS |version|" tab3="QGIS testing (>|ltrversion|)" tab4="Archived releases">}}

URL mapping from old site structure Copy Chapter

This table represents required redirects from old URL structure to the new one:
https://docs.google.com/spreadsheets/d/12Oo761Zwgj4iLeJxdrg8I31rGzsB95z5M1PpW9pYma8/edit?usp=sharing

Notes:

• it will be more convenient to store all redirects in same file (nginx conf or else)
• hugo aliases not recommended: they work, but don't support regex. also hard to maintain: redirects are spread across content files
• use regexps to redirect from all langs
• use regexps to map between similar stuff (case studies, visual changelog) - example rewrite rules below

Bulk redirects can be done like

map $url $new_url {
	...
    ^/[A-Za-z-]+/site/about/case_studies/(.*).html /project/case-studies/$1/;
    ^/[A-Za-z-]+/site/forusers/visualchangelog(.*)/index.html /project/visual-changelogs/visualchangelog$1/;
	^/[A-Za-z-]+/site/forusers/usergroups.html /community/organisation/groups/;
	...
}

See nginx map tutorial and examples with regex capture

Stripe donations Copy Chapter

main donation page: https://qgis.github.io/QGIS-Website/funding/donate/

Stripe widget can be included to any page with the shortcode {{<stripe-widget>}}

Payment options are implemented with Payment Links. Values and links can be updated in data/stripe_products.yml

Note: payment links also support recurring donations (subscriptions) - products with recurrent payments should be created for that matter

Donors update from a static file Copy Section

The Donors list stored in data/donors.json can be updated from one or multiple
static txt file using the script script/update_donors_from_file.py:

python scripts/update_donors_from_file.py   ...

Donors scraping Copy Section

Is not ported yet. Donors are stored in data/donors.json. adddonor.pl and related scripts & webhooks should be adapted to the new format

Auto-checking for broken links Copy Chapter

docker run --rm dcycle/broken-link-checker:3 https://qgis.github.io/QGIS-Website > broken_links.csv

Crawls the site and reports all 404 errors. Full run takes about 10 mins

Made with ❤️ by Tim Sutton (@timlinux), Lova Andriarimalala (@Xpirix) and QGIS Contributors.