Enable importing from system-installed QGIS

[lbartoletti]

Description

This PR proposes using the system-installed QGIS Python environment instead of assuming execution inside a virtualenv, Conda, Mamba, or similar isolated environment.

The main change introduces a lightweight qgis_loader that:

Dynamically adds the appropriate system QGIS Python paths to sys.path, depending on the operating system.

Ensures that QGIS can be imported from a native system installation.

Allows backend checks to rely on the actual availability of system QGIS rather than a bundled Python environment.

This approach is particularly useful when working with distributions where QGIS is provided as system packages. In my case, it enables running JupyterGIS QGIS on FreeBSD, and is a prerequisite for packaging it properly on that platform.

Additionally, this PR fixes the PyQt import to explicitly use qgis.PyQt, which is the recommended best practice for QGIS plugins and avoids mismatches between system Qt/PyQt installations and the one shipped with QGIS.

Checklist

• PR has a descriptive title and content.
• PR description contains references to any issues the PR resolves, e.g. Resolves #XXX.
• PR has one of the labels: documentation, bug, enhancement, feature, maintenance
• Checks are passing.
  Failing lint checks can be resolved with:
  • pre-commit run --all-files
  • jlpm run lint
• If you wish to be cited for your contribution, CITATION.cff contains an author entry for yourself

---

📚 Documentation preview: https://jupytergis--1064.org.readthedocs.build/en/1064/
💡 JupyterLite preview: https://jupytergis--1064.org.readthedocs.build/en/1064/lite

[github-actions]

👈 Launch a Binder on branch lbartoletti/jupytergis/fix_qgis_import

[mfisher87]

Thank you for this contribution!

I personally avoid using system-installed QGIS because it tends to be pretty out-of-date, so I almost always use a version installed with a conda package manager (I'm all in on pixi these days). The closest I come is using flatpak! I really appreciate that you're bringing a different perspective with this PR ❤️

[mfisher87]

what do you think of logger.critical instead of print?

[lbartoletti]

Sure, do you want me to also fix other print in a different commit?

[mfisher87]

Good point, this file does already have a bunch of print calls in it. Let's keep the print calls as they are for consistency with the existing code, and we'll worry about swapping them over to logger calls in another PR!

[github-actions]

Integration tests report: appsharing.space

[lbartoletti]

Thank you for this contribution!

Thanks to you and the project!

I personally avoid using system-installed QGIS because it tends to be pretty out-of-date, so I almost always use a version installed with a conda package manager (I'm all in on pixi these days). The closest I come is using flatpak!

Yes, I can understand that. But it really depends on the systems or distributions. BSDs tend to be bleeding edge, as do certain Linux distributions where you always have the latest versions; this is obviously not the case with distributions such as Ubuntu or Debian.

I really appreciate that you're bringing a different perspective with this PR ❤️

Thanks 😊

Stale

[mfisher87]

I'll try and make some time to play with this and merge tomorrow!

[SylvainCorlay]

This PR proposes using the system-installed QGIS Python environment instead of assuming execution inside a virtualenv, Conda, Mamba, or similar isolated environment.

I am really not sure about adding complexity to handle installing qgis in a separate prefix as jupytergis makes sense.

[mfisher87]

@SylvainCorlay I do think there's value in supporting a system QGIS installation, my only concern is the lack of ability for us to express constraints (i.e. run_constrained in a conda recipe) that might prevent end users from hitting issues with QGIS versions that break compatibility with the interfaces we use (though I feel pretty confident in the stability of QGIS' interfaces). A workaround for that might be runtime checks, but I feel we can deal with that problem if/when we get there.

I think it's important to acknowledge that end-users may not be "environment-pilled" (as my colleague @GondekNP might say -- meaning they aren't "all-in" on using isolated environments; they may think "Why do I need so many QGIS installations? I don't want to waste disk space!"). I think in this case, meeting the user where they are is the right choice, so my vote on this change is a strong 👍

But maybe we should gather some more input? @ing some folks from various orgs for their thoughts, no other rhyme or reason: @tylere @YaoTingYao @annefou @martinRenou ?

[SylvainCorlay]

I don't think it is ever a good idea to extend sys.path with absolute paths from completely different python installations, which will can (and will) have different versions of packages and python itself than the version currently in use. The number of ways in which it can break is really high, not to mention that most Linux distribution heavily patch CPython.

If we really want to communicate with an installation of qgis that is not installed in the same installation prefix as jupytergis, using a message passing method would be a lot safer and cleaner, bout would also be a very different endeavor.

[mfisher87]

@lbartoletti I'd love to hear your thoughts on @SylvainCorlay 's comment! I don't know much about how QGIS packages Python so my plan was to learn by doing and just play with this PR in a Docker container with system-installed QGIS to see if I could break anything :)

[SylvainCorlay]

We should not extend sys.path with other installation prefixes.

[lbartoletti]

@SylvainCorlay I fully understand your concerns about the risks of manipulating sys.path with paths from other Python installations.

I've reworked the approach to find a compromise that hopefully works for everyone:

Using explicit opt-in via JGIS_QGIS_PATH (obviously, I'm open to any adjustments).

So we keep the default behavior: no sys.path modification (conda/pixi/venv). But, when needed, the user can explicitly set JGIS_QGIS_PATH pointing to their system QGIS installation.

So, for myself, I can use it like this: env JGIS_QGIS_PATH=/usr/local/share/qgis/python jupyter lab

This behavior does not break existing functionality, and we can emphasize that the use of this variable is the user’s responsibility.