Installation

The EnMAP-Box is a plugin for QGIS and requires additional python packages that need to be installed independent from QGIS.

Video with step by step installation instructions

1. Install QGIS

Install QGIS version 3.26 or higher to run the EnMAP-Box. You can get QGIS here. Additional information on the installation process is provided in the QGIS Documentation.

In case you already have QGIS installed, you can skip this step.

MacOS

Before you can install QGIS from the downloaded disk image, you need to allow your macOS to install it:

  1. Download the official all-in-one, signed installer here.

  2. Extract the downloaded qgis-macos-pr.dmg and move it to your app folder

    mac_copy1 mac_copy2

  1. Installing or opening QGIS may raise a verification warning. In that case, open your system preferences, go to Security & Privacy ‣ General and allow QGIS to be opened anyway.

    mac_check1 mac_check2

  1. Now you can start QGIS.app from your application folder.

2. Install required python packages

The EnMAP-Box plugin requires several python packages (click here here for full list). In the following we demonstrate two variants for installing the required packages (you don’t have to do both!):

2.1 Package Installer

The EnMAP-Box includes a Package Installer that offers a more or less one-click solution to install required python packages. It can be accessed from the menu bar via Project ‣ Package Installer.

If you start the EnMAP-Box for the first time, you may see a warning. The Package Installer can also be opened by clicking Install Missing.

../_images/warning_missing_packages.png

Use the Yes to All button to install all required python packages. Per default, this will install packages using pip into the user directory (as this does not require admin rights). It is also possible to install/update packages individually via the context menu inside the package list.

../_images/package_installer.png

It might be necessary to restart QGIS and the EnMAP-Box.


2.2 Command-line

In case the Package Installer does not work for you or you do not want to use it, try installing the packages from the command-line. This variant may be more reliable. See OS specific instructions below:

Windows

  1. Close QGIS, if it is open.

  2. Run the OSGeo4W Shell as administrator, if possible. A convenient way to access the OSGeo4W Shell is from the start menu. Depending on the installation method you used to install QGIS, the shortcut will be listed under QGIS 3.xx (standalone installer) or OSGeo4W (network installer)

    Hold Ctrl + Shift and click on the OSGeo4W Shell entry (or right-click and choose Run as administrator)

    ../_images/windows_start_osgeo.png

  3. Activate the Python 3 environment by entering:

    py3_env
    ../_images/shell_callpy3env.png

    Note

    In more recent versions of QGIS the py3_env call might not be necessary or will simply not work. If so, just continue with the following step (4).

  4. Install required python packages by entering:

    python3 -m pip install -r https://raw.githubusercontent.com/EnMAP-Box/enmap-box/main/requirements.txt

    Now all packages will be installed automatically. After completion, the shell should show something like this:

    ../_images/shell_install_output.png

    If the package installation was successful, you can close the shell. The required packages are installed now and you can continue to start/install the EnMAP-Box.

    Error

    In case you run into problems because pip is not available in your python environment (error message C:/.../python3.exe: No module named pip or similar), follow these steps…


Linux

  1. Close QGIS, if it is open.

  2. Open the terminal and install all missing packages using pip:

    python3 -m pip install -r https://raw.githubusercontent.com/EnMAP-Box/enmap-box/main/requirements.txt

    Hint

    Make sure to execute the pip command in the python environment QGIS is using (usually you can find out where python is located by running import sys; sys.executable in the QGIS Python Console). You then might have to change the python3 part in the snippet below with the explicit QGIS python path.

    This also applies if you installed QGIS using flatpak, in that case install python modules as described here.

    Note

    You might also consider to create a virtual environment (python3 -m venv), install the packages as described, set system-site-packages = true in the pyvenv.cfg, activate this virtual environment and start qgis from there.


Mac

To install single python packages like the astropy package, open the Terminal and call:

/Applications/QGIS.app/Contents/MacOS/bin/pip3 install -U astropy

Use -U or --update to update older package version.

To install all packages required, call:

/Applications/QGIS.app/Contents/MacOS/bin/pip3 install -U -r https://raw.githubusercontent.com/EnMAP-Box/enmap-box/main/requirements.txt

More details on the QGIS packaging mechanism for macOS can be found here.


Error

See FAQ if you run into problems installing the packages.


3. Install or update the EnMAP-Box

Install from QGIS plugin repository

  1. Open QGIS and go to Plugins ‣ Manage and Install Plugins ‣ All

  2. In the search bar enter enmap or EnMAP-Box 3

  3. Now the EnMAP-Box should be listed in the plugin list:

    ../_images/pluginmanager_all.png

    Select it and click Install plugin (or Upgrade in case you update to a new version)

  4. The following dialog might pop up afterwards:

    ../_images/plugin_dep_manager.png

    Depending on whether you want to use the GEE Time Series Explorer check cb1 or uncheck cb0 the checkbox and confirm with OK

  5. Start the EnMAP-Box via the icon icon or from the menubar Raster ‣ EnMAP-Box

  6. (Optional): You can download a demo dataset via Project ‣ Load Example Data

Experimental version

It is also possible to install the most recent develop version of the EnMAP-Box. To do so, make sure that the option cb1 Show also experimental plugins is activated in the plugin manager settings. Once activated, there is an additional button Install Experimental Plugin in the plugin manager.

../_images/experimental_install.png

Warning

As the experimental tag suggests, this version comes with the newest features and developments, but might also be prone to bugs and crashes.

Install older version

  1. Go to the QGIS Python Plugins Repository https://plugins.qgis.org/plugins/enmapboxplugin/
  2. Click on the Versions tab to see all available version.
  3. Click on the desired version and on the next page click download
  4. It is recommended to uninstall previous EnMAP-Box versions (delete folder manually, or in QGIS via Plugins ‣ Manage and Install Plugins ‣ Installed ‣ EnMAP-Box 3 ‣ Uninstall plugin)
  5. Open Plugins ‣ Manage and Install Plugins ‣ Install from ZIP.
  6. Press … and select the downloaded zip file (enmapboxplugin.3.x.YYYYMMDDTHHMM.QGIS3.zip) and click Install plugin.
  7. Start the EnMAP-Box via the icon icon or from the menubar Raster ‣ EnMAP-Box.