Installation#

Important

It’s always a good idea to use virtual environments. Installing into a global environment can get you in trouble later!

These instructions presuppose that you know how to create and activate virtual environments with your tool of choice.

Installing the latest stable release#

Tip

Installing with a conda-based tool (mamba, conda, micromamba, or pixi) lets you install qgis alongside JupyterGIS, enabling .qgz file support. QGIS is a C++ application and cannot be installed via pip or uv.

mamba install -c conda-forge jupytergis qgis
jupyter lab  # Start JupyterLab!

Warning

When installing with pip, QGIS compatibility and optional tiler functions won’t work out of the box. You may especially run in to problems with Python 3.14, for which many geospatial libraries still lack wheels as of May 2026. You’re on your own!

pip install jupytergis
jupyter lab  # Start JupyterLab!

Tip

Installing with a conda-based tool (mamba, conda, micromamba, or pixi) lets you install qgis alongside JupyterGIS, enabling .qgz file support. QGIS is a C++ application and cannot be installed via pip or uv.

Install into a project:

pixi add jupytergis qgis
pixi run jupyter lab  # Start JupyterLab!

Or run directly without a permanent install:

pixi exec --spec jupytergis --spec qgis jupyter lab

Warning

When installing with pip, QGIS compatibility and optional tiler functions won’t work out of the box. You may especially run in to problems with Python 3.14, for which many geospatial libraries still lack wheels as of May 2026. You’re on your own!

Install into a project:

uv add jupytergis
uv run jupyter lab  # Start JupyterLab!

Or run directly without a permanent install:

uv run --with jupytergis jupyter lab

docker run -p 8888:8888 ghcr.io/geojupyter/jupytergis:latest

Docker build source: geojupyter/jupytergis-docker

Installing dynamic tiling functionality#

To use dynamic tiling functionality, you’ll need our “tiler” optional dependencies.

For any of the above commands, replace jupytergis with jupytergis[tiler] (for pip/uv) or jupytergis-tiler (for conda/mamba/pixi).

Note

This functionality is available as of version 0.16.0.

Installing a pre-release#

To install a pre-release, replace install commands shown above with these examples. Changes include:

  • Specify a pre-release version exactly; here’s we’re using pre-release 0.16.0a4 as an example.

  • When installing a Conda package with mamba/conda/pixi, add the pre-release channel as highest priority channel.

  • When installing a PyPI package with pip/uv, add a flag to allow installing pre-releases.

mamba install \
  --channel conda-forge/label/jupytergis_prerelease \
  --channel conda-forge \
  jupytergis==0.16.0a4 qgis
jupyter lab  # Start JupyterLab!

pip install --pre jupytergis==0.16.0a4
jupyter lab  # Start JupyterLab!

Without a permanent install:

pixi exec \
  --channel conda-forge/label/jupytergis_prerelease \
  --channel conda-forge \
  --spec jupytergis==0.16.0a4 \
  --spec qgis \
  jupyter lab

Without a permanent install:

uv run --prerelease=allow --with jupytergis==0.16.0a4 jupyter lab