Installation

The Installation section explains how to set up EnMAP‑Box as a QGIS plugin on your computer. It guides you through installing a compatible QGIS version, preparing the required Python environment, and then adding EnMAP‑Box via the QGIS Plugin Manager or from a specific release.

1. QGIS and Python Dependencies

Install QGIS via the official Standalone/OSGeo4W Installer

Install the current QGIS 3.44 LTR to run the latest EnMAP-Box using the QGIS installer from https://www.qgis.org/en/site/forusers/alldownloads.html#windows.

Install Python Dependencies

Close QGIS.

Open the OSGeo4W shell.
Install OSGeo4W managed dependencies (and update QGIS):
setup -q -g -P python3-scipy,python3-matplotlib,python3-colorama,python3-defusedxml,python3-sympy,python3-h5py,gdal-hdf5,python3-pip,python3-setuptools,python3-sympy,python3-numba,python3-netcdf4,python3-pyopengl,python3-scikit-learn
Install PIP managed dependencies:
pip install --upgrade --user -r https://raw.githubusercontent.com/EnMAP-Box/enmap-box/main/.env/osgeo4w/requirements_osgeo4w.txt
Note

In rare cases, the user site-packages folder may contain wrongly installed packages, which are interfering with the package version managed by OSGeo4W, e.g. numpy, scipy or gdal. Wrongly installed packages can be deleted manually.

To locate the user folder used by your QGIS instance, run the following inside your QGIS Python console:
>>> import site
>>> print(site.USER_SITE)
C:\Users\<user name>\AppData\Roaming\Python\Python39\site-packages
Open QGIS.

Warning

The Linux bare-metal installation uses the operating-system QGIS and Python environment. This is useful when you want a native QGIS installation without conda, but it is less isolated than the Conda setup. If dependency versions become difficult to resolve, use the Conda tab.

Install QGIS on Linux (bare-metal / apt)

The commands below install the QGIS 3.44 LTR packages on Ubuntu. For Debian, use the corresponding https://qgis.org/debian-ltr repository and Debian suite name.

Open the Terminal (Ctrl + Alt + T).

Install the packages needed to add the QGIS package repository:

sudo apt update
sudo apt install ca-certificates gnupg wget
sudo install -d -m 0755 /etc/apt/keyrings
sudo wget -qO /etc/apt/keyrings/qgis-archive-keyring.gpg https://download.qgis.org/downloads/qgis-archive-keyring.gpg

Add the QGIS LTR repository. Use noble for Ubuntu 24.04 and jammy for Ubuntu 22.04.

sudo tee /etc/apt/sources.list.d/qgis.sources >/dev/null <<'EOF'
Types: deb deb-src
URIs: https://qgis.org/ubuntu-ltr
Suites: noble
Architectures: amd64
Components: main
Signed-By: /etc/apt/keyrings/qgis-archive-keyring.gpg
EOF

Install QGIS and PyQGIS:

sudo apt update
sudo apt install qgis python3-qgis qgis-plugin-grass

Install Python Dependencies

Install the system packages required by common EnMAP-Box workflows:

sudo apt install python3-pip python3-venv pyqt5-dev-tools python3-matplotlib

(Optional) For some EnMAP-Box tools you may also need the following packages:
```
sudo apt install python3-h5py python3-pyqt5.qtopengl python3-netcdf4
```

Install the remaining EnMAP-Box Python dependencies into your user Python site:

python3 -m pip install --user --upgrade --ignore-installed -r https://raw.githubusercontent.com/EnMAP-Box/enmap-box/main/.env/linux/requirements_ubuntu.txt || \
python3 -m pip install --user --upgrade --ignore-installed --break-system-packages -r https://raw.githubusercontent.com/EnMAP-Box/enmap-box/main/.env/linux/requirements_ubuntu.txt

On Ubuntu 24.04, pip may require --break-system-packages for user-site installs because the system Python environment is externally managed.

Verify that QGIS uses the same Python installation:

python3 -c "from qgis.core import Qgis; print(Qgis.QGIS_VERSION)"

Start QGIS:
```
qgis
```

Hint

You can add a shortcut to your applications menu, so you do not have to open a Terminal and type the above-mentioned commands (6 & 8) every time you want to start QGIS with the EnMAP-Box environment:

Create the file ~/.local/share/applications/enmapbox.desktop with the following content (if you used another installation path in the instructions above, change accordingly):

[Desktop Entry]
Name=QGIS (EnMAP-Box)
Exec=/bin/bash -c "source ~/.virtualenvs/enmapbox/bin/activate && qgis %F"
Terminal=false
Icon=qgis
Type=Application
Categories=Education;Science;Geography;

Warning

The internal Python environment in macOS QGIS.app’s restricts isolated package builds, but these are required by EnMAP-Box applications like the EnMAP Processing Tool (EnPT).

We therefore recommend to install QGIS and the Python dependencies required to run the EnMAP-Box using Conda (see the *Conda* tab). This is significantly easier to manage, update, and resolve QGIS and dependency versions over time.

Install QGIS on MacOS

Install QGIS using the official macOS installer (e.g., version 3.44 LTR) from the QGIS Download Page. Download the .dmg file, open it, and drag QGIS to your Applications folder.

Install Python Dependencies

Modern QGIS installations on macOS embed Python deeply within the application framework, meaning traditional terminal commands (like calling pip3 from the bin folder) are no longer reliable. To safely install dependencies to the correct environment, you must execute the installation directly from within QGIS.

Launch QGIS.
Navigate to Plugins ‣ Python Console in the top menu bar.
Copy the script below, paste it into the console prompt (>>>), and press Enter:

import sys
import os
import runpy

# 1. Manually create the missing 'bin' directory so pip stops crashing
broken_bin_path = "/Applications/QGIS.app/Contents/Frameworks/bin"
os.makedirs(broken_bin_path, exist_ok=True)

print("Created missing bin directory. Finishing installation...")

original_argv = sys.argv
enmap_packages = [
    "colorama", "astropy", "PyOpenGL", "xgboost", "lightgbm",
    "catboost", "sympy", "numba>=0.57", "scikit-learn>=1.0"
]

# 2. run pip with a flag to silence the script warnings
sys.argv = ["pip", "install", "-U", "--no-warn-script-location"] + enmap_packages

try:
    runpy.run_module("pip", run_name="__main__")
except SystemExit:
    pass
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    sys.argv = original_argv
    print("=========================================")
    print("All packages are now fully installed!")
    print("You can safely activate EnMAP-Box 3.")
    print("=========================================")

Wait for the packages to download and compile. Once the console prints the success message, you can close the Python Console.

Install QGIS and Python dependencies with conda (cross-platform)

Conda is a cross-platform package manager that allows to install software in separated environments. We recommend to install and use Miniforge, a minimal conda installer specific to packages from conda-forge channel. It contains a meta-package for packages needed by the EnMAP-Box https://anaconda.org/channels/conda-forge/packages/enmapbox/overview

Open a conda terminal and create a conda environment that contains QGIS and all required packages.
1. Use the enmapbox recipe to install packages required to run the EnMAP-Box, including EnPT, EnFROSP, SpecDeepMap
```
conda create -n enmapbox -c conda-forge enmapbox
```
2. Use the enmapbox-lite recipe to install packages required to run the EnMAP-Box and most machine-learning applications
```
conda create -n enmapbox -c conda-forge enmapbox-lite
```
Activate the conda environment and start QGIS:

conda activate enmapbox
qgis

Note

QGIS, GDAL and other packages are developing rapidly. To keep an environment <env_name> up to date, call:

conda activate <env_name>
(<env_name>) conda update --all

To delete a conda environment, call:

conda env remove -n <env_name>

To use a specific package version, call conda install <package>=<version>. Such a step may require an update of various other packages. For example to use a specific QGIS version, call:

conda activate <env_name>
(<env_name) conda install qgis=3.40

2. Install EnMAP-Box

Install EnMAP-Box Plugin via the QGIS Plugin Manager

Start QGIS.
Go to Settings ‣ User Profiles ‣ New Profile… and create a profile named EnMAP-Box.
Restart QGIS in the EnMAP-Box profile if QGIS does not switch automatically.
Go to Plugins ‣ Manage and Install Plugins.
Search for EnMAP-Box.
Click Install Plugin.

Activate Experimental Plugins (Optional)

Go to Plugins ‣ Manage and Install Plugins ‣ Settings.
Enable Show also Experimental Plugins.

The qgis-plugin-manager allows you to install QGIS plugins like EnMAP-Box from the command line. The commands below create a dedicated QGIS profile named EnMAP-Box and install the plugin into that profile.

export QGIS_PROFILE="EnMAP-Box"
export QGIS_PROFILE_HOME="${HOME}/.local/share/QGIS/QGIS3/profiles/${QGIS_PROFILE}"
export QGIS_PLUGINPATH="${QGIS_PROFILE_HOME}/python/plugins"
export PATH="${HOME}/.local/bin:${PATH}"

mkdir -p "${QGIS_PLUGINPATH}" "${QGIS_PROFILE_HOME}/QGIS"

python3 -m pip install --user --upgrade --ignore-installed qgis-plugin-manager || \
python3 -m pip install --user --upgrade --ignore-installed --break-system-packages qgis-plugin-manager

qgis-plugin-manager init --qgis-version 3.44 --update
qgis-plugin-manager install "EnMAP-Box 3" --upgrade --fix-permissions

printf '[PythonPlugins]\nenmapboxplugin=true\n' \
  | tee "${QGIS_PROFILE_HOME}/QGIS/QGIS.ini" "${QGIS_PROFILE_HOME}/QGIS/QGIS3.ini" > /dev/null

qgis --profile "${QGIS_PROFILE}"