Installation with pipx

pipx installs a Python CLI application into its own isolated virtual environment while exposing its commands globally. It’s a convenient way to install dicogis-cli (or dicogis-gui) without polluting your system Python or manually managing a virtual environment.

python -m pip install --user pipx
pipx ensurepath

The GDAL challenge

DicoGIS relies on GDAL/OGR to read geospatial datasets. GDAL is declared as an optional dependency (the gdal extra in pyproject.toml), so pipx install dicogis always succeeds and dicogis-cli --help / dicogis-cli --version always work — but any command that actually reads data (dicogis-cli inventory, dicogis-gui) will refuse to run and tell you GDAL is missing.

The reason GDAL can’t just be a normal dependency is that the gdal Python package on PyPI is not a portable wheel: it must match the version of the libgdal system library it links against (gdal-config --version), which pip cannot resolve on its own inside an isolated pipx venv. You need to get a matching GDAL into that venv yourself, using one of the options below.

Linux (Debian/Ubuntu)

First, install the GDAL system library and its gdal-config companion (see Develop on Ubuntu for PPA options if you need a specific version):

sudo apt install gdal-bin libgdal-dev

Then choose one of:

Option B — build GDAL into the isolated pipx venv

pipx install dicogis
pipx inject dicogis "gdal[numpy]==$(gdal-config --version).*"

This compiles the gdal Python package against your system libgdal, so it needs libgdal-dev and a build toolchain (build-essential) available.

Verify

dicogis-cli inventory --input-folder ./some/folder

Windows

There is no official portable gdal wheel for Windows on PyPI. Two options:

Option A — inject an unofficial prebuilt wheel

Download the wheel matching your Python version from cgohlke/geospatial-wheels (e.g. GDAL-3.11.1-cp312-cp312-win_amd64.whl for Python 3.12), then:

pipx install dicogis
pipx inject dicogis C:\path\to\GDAL-3.11.1-cp312-cp312-win_amd64.whl

Option B — use conda instead of pipx

If you’d rather avoid manual wheels, install DicoGIS in a conda/mamba environment, where GDAL is available as a prebuilt package:

conda create -n dicogis -c conda-forge python=3.12 gdal
conda activate dicogis
pip install dicogis

The GUI extra

dicogis-gui additionally needs PyQt6, declared as an optional dependency too (the gui extra), so pipx install dicogis / dicogis-cli never require it:

pipx inject dicogis PyQt6
# or: pip install dicogis[gui]

Prebuilt executables

If you’d rather not deal with GDAL at all, the releases on GitHub ship standalone CLI/GUI executables (Windows and Ubuntu) that embed GDAL — no Python or pipx required. See the “Try it” section on the documentation home page.

Docker

A container image for dicogis-cli is published to the GitHub Container Registry, built on top of the official GDAL images so GDAL is already installed and version-matched — nothing to compile or inject.

docker pull ghcr.io/guts/dicogis:latest
docker run --rm -v "$(pwd)":/data ghcr.io/guts/dicogis:latest \
    inventory --input-folder /data --output-path /data/dicogis_inventory.xlsx

The entrypoint is dicogis-cli, so any dicogis-cli subcommand/option works the same way, e.g. docker run --rm ghcr.io/guts/dicogis:latest --version. The working directory inside the container is /data; mount your input folder (and/or pg_service.conf for PostGIS) there. Tags follow the project’s releases (X.Y.Z, X.Y) plus edge (latest master).