[QGIS-Developer] Development environment setup

Tue Nov 11 00:47:45 PST 2025

Hi all,

Great that we are talking about the difficulties of building QGIS. I just
wanted to also share my way of building QGIS using Distrobox (
https://github.com/89luca89/distrobox). I have tried local and few
containerization methods and VCPKG but I find Distrobox to be easily the
fastest and the most stable way.

Here are the steps in a nutshell:

   1. Download Distrobox in any linux distro
   2. Check the suitable build deps image for your needs in
   https://hub.docker.com/u/qgis . I used
   *qqgis3-build-deps-ubuntu-qt6:latest* which contains every dependency
   needed for building QGIS with QT6 support
   3. In terminal run:
   distrobox create --image
   docker.io/qgis/qqgis3-build-deps-ubuntu-qt6:latest --additional-packages
   "qtcreator" qgis-dev
   4. Allow using graphical interface within distrobox by running:
   xhost +
   5. Connect to box:
   distrobox enter qgis-dev
   6. Start qtcreator (or CLion which is my IDE of choice) in the terminal
   and start building QGIS normally
   7. You might want to set -DWITH_INTERNAL_SPATIALINDEX=ON
   and -DWITH_PDAL=OFF since build dep images do not contain the deps for
   those.
   8. QGIS can be started and debugged normally and has access to all your
   local data just like in the normal local environment and even local (or
   container) databases can be accessed easily via your computer's ip
address (ip
   addr show)

All the tasks prior to building take about 10 minutes and the development
experience is superior to any other method I have tried so far. I can see
that .devcontainer folder is in .gitignore so there is at least some
developers that are using Devcontainers with QGIS as well, but it would be
great if that way could also be officially supported.

Cheers,
Joona

ti 11.11.2025 klo 10.16 Samweli Twesa Mwakisambwe via QGIS-Developer (
qgis-developer at lists.osgeo.org) kirjoitti:

> Hi Tom,
>
> Here is a suggested alternative approach that I have documented recently
> https://samweli.github.io/QGIS-Development-Using-Docker
>
> It may address some of the challenges you have mentioned and there is a
> potential to align both efforts or incorporate improvements from your
> implementation.
>
>
> Best,
> Samweli
>
> On Fri, Nov 7, 2025 at 3:45 AM Tom Christian via QGIS-Developer <
> qgis-developer at lists.osgeo.org> wrote:
>
>> Hi All,
>>
>> I am interested in learning more about how QGIS developers configure
>> their development environments, and I would like to get some feedback on an
>> alternate approach.
>>
>> I recently contributed my first changes to QGIS and I found the
>> development environment quite challenging. While the QGIS Developers
>> Guide <https://docs.qgis.org/3.40/en/docs/developers_guide/index.html> contains
>> lots of information I found most of it to be high-level, e.g. how to work
>> with Git, and there was limited information on gathering required
>> dependencies and setting build configurations.
>>
>> Given the number of dependencies, the risk of conflicts with existing
>> packages, and my strong preference to avoid VMs, I thought a containerised
>> build environment was ideal. My work requires frequently switching between
>> projects and environments. I generally cannot let any one project's
>> dependencies pollute the system outside of a Conda environment, a
>> container, or a VM.
>>
>> I found the CI Docker configuration
>> <https://github.com/qgis/QGIS/tree/master/.docker> and thought I could
>> use this to build and test QGIS. These Dockerfiles should guarantee all
>> required dependencies AND this is the environment that passes or fails CI
>> checks on my changes. Building QGIS using the CI Docker configuration
>> was OK, but CI is not setup for running the build product in a container -
>> meaning changes cannot quickly be manually / visually tested in this way.
>> The project would have to be compiled (with the benefit of mounted ccache)
>> and installed every time the container was started before the application
>> could run. The long Docker commands are not currently scripted outside of
>> GitHub Actions Workflows, and build configurations are provided via
>> matrices, so replicating these processes locally is non-trivial.
>>
>> I created this repo
>> <https://github.com/sparkgeo/QGIS-Container-Development> to better
>> automate container-based development and testing of QGIS. It contains build
>> / run / test scripts, .env configurations, and Docker Compose overrides to
>> work with the QGIS CI Docker configuration with as few changes as possible.
>> It currently requires a single small commit
>> <https://github.com/sparkgeo/QGIS-EOPF/commit/64b6f6568ec24f9a064a24869b3d1fb95a6ae0b1> in
>> the active QGIS branch to support this approach, which I removed before
>> creating PRs for the main QGIS repo.
>>
>> With this approach, building and running a containerised QGIS development
>> build is (in theory) as simple as scripts/run.sh. Tests can be executed
>> with scripts/test.sh.
>>
>>
>> I have some questions:
>>
>> 1) are you installing QGIS build dependencies on "bare metal", or perhaps
>> using a VM?
>> 2) is there a simpler approach than this for containerised builds, runs,
>> and tests?
>>   2a) if not, is there any interest in pursuing this or a similar
>> approach to simplify containerised development environments?
>>
>>
>> Ultimately I suspect the QGIS project would benefit from lower barriers
>> to entry and the ability to better isolate build dependencies.
>>
>> _______________________________________________
>> QGIS-Developer mailing list
>> QGIS-Developer at lists.osgeo.org
>> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>>
>
>
> --
>
>
> All the Best,
>
> Samweli
> _______________________________________________
> QGIS-Developer mailing list
> QGIS-Developer at lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20251111/e94f2336/attachment-0001.htm>