Installing OGGM

Important

Did you know that you can try OGGM in your browser before installing it on your computer? Visit Try OGGM online for more information.

OGGM itself is a pure Python package, but it has several dependencies which are not trivial to install. The instructions below provide all the required detail and should work on Linux and Mac OS. See Installation troubleshooting if something goes wrong.

OGGM is fully tested with Python version 3.6 and 3.7 on Linux. OGGM doesn’t work with Python 2. We do not test OGGM on Mac OS, but it should probably run fine.

Warning

OGGM does not work on Windows. If you are using Windows 10, we strongly recommend to install the free Windows subsytem for Linux and install and run OGGM from there.

For most users we recommend to install Python and the package dependencies with the conda package manager. Linux users with experience with pip can follow these instructions to install OGGM in a pyenv environment with pip.

Dependencies

Here is a list of all dependencies of the OGGM model. If you want to use OGGM’s numerical models only (i.e. no GIS or preprocessing tools), refer to Install a minimal OGGM environment below.

Standard SciPy stack:
  • numpy
  • scipy
  • scikit-image
  • pillow
  • matplotlib
  • pandas
  • xarray
  • dask
  • joblib
Configuration file parsing tool:
  • configobj
I/O:
  • netcdf4
  • pytables
GIS tools:
  • shapely
  • pyproj
  • rasterio
  • geopandas
Testing:
Other libraries:
Optional:
  • progressbar2 (displays the download progress)
  • bottleneck (might speed up some xarray operations)
  • python-colorspace (applies HCL-based color palettes to some graphics)

Install with conda (all platforms)

This is the recommended way to install OGGM for most users.

Note

If you are not familiar with Python and its way too many package management systems, you might find all of this quite confusing and overwhelming. Be patient, read the docs and stay hydrated.

Prerequisites

You should have a recent version of the conda package manager. You can get conda by installing miniconda (the package manager alone - recommended) or anaconda (the full suite - with many packages you won’t need).

Conda environment

We recommend to create a specific environment for OGGM. In a terminal window, type:

conda create --name oggm_env python=3.X

where 3.X is the Python version shipped with conda (currently 3.8). You can of course use any other name for your environment.

Don’t forget to activate it before going on:

source activate oggm_env

Feeling adventurous? Try mamba

The conda package manager has recently been criticized for being slow (it is quite slow to be honest). A new, faster tool is now available to replace conda: mamba. Mamba is a drop-in replacement for all conda commands. If you feel like it, install mamba in your conda environment (conda install -c conda-forge mamba) and replace all occurrences of conda with mamba in the instructions below.

Dependencies

Install all OGGM dependencies from the conda-forge and oggm conda channels:

conda install -c oggm -c conda-forge oggm-deps

The oggm-deps package is a “meta package”. It does not contain any code but will install all the packages OGGM needs automatically.

Important

The conda-forge channel ensures that the complex package dependencies are handled correctly. Subsequent installations or upgrades from the default conda channel might brake the chain. We strongly recommend to always use the the conda-forge channel for your installation.

You might consider setting conda-forge as your default channel:

conda config --add channels conda-forge

No scientific Python installation is complete without installing a good testing framework, as well as IPython and Jupyter:

conda install -c conda-forge pytest ipython jupyter

Install OGGM itself

First, choose which version of OGGM you would like to install:

  • stable: this is the latest version officially released and has a fixed version number (e.g. v1.1). As of today (Sept 2020), we do not recommend to install the stable version which is quite outdated. We are in the process of releasing a new stable version soon(ish).
  • dev: this is the development version. It might contain new features and bug fixes, but is also likely to continue to change until a new release is made. This is the recommended way if you want to use the latest changes to the code.
  • dev+code: this is the recommended way if you plan to explore the OGGM codebase, contribute to the model, and/or if you want to use the most recent model updates.

‣ install the stable version:

If you are using conda, you can install stable OGGM as a normal conda package:

conda install -c oggm oggm

If you are using pip, you can install OGGM from PyPI:

pip install oggm

‣ install the dev version:

For this to work you’ll need to have the git software installed on your system. In your conda environment, simply do:

pip install --upgrade git+https://github.com/OGGM/oggm.git

With this command you can also update an already installed OGGM version to the latest version.

‣ install the dev version + get access to the OGGM code:

For this to work you’ll need to have the git software installed on your system. Then, clone the latest repository version:

git clone https://github.com/OGGM/oggm.git

Then go to the project root directory:

cd oggm

And install OGGM in development mode (this is valid for both pip and conda environments):

pip install -e .

Note

Installing OGGM in development mode means that subsequent changes to this code repository will be taken into account the next time you will import oggm. You can also update OGGM with a simple git pull from the root of the cloned repository.

Testing OGGM

You can test your OGGM installation by running the following command from anywhere (don’t forget to activate your environment first):

pytest --pyargs oggm

The tests can run for about 10 minutes (we are trying to reduce this). If everything worked fine, you should see something like:

================================ test session starts ================================
platform linux -- Python 3.8.5, pytest-6.0.2, py-1.9.0, pluggy-0.13.1
Matplotlib: 3.3.2
Freetype: 2.6.1
rootdir: /home/mowglie/disk/Dropbox/HomeDocs/git/oggm-fork, configfile: pytest.ini
plugins: mpl-0.122
collected 297 items

oggm/tests/test_benchmarks.py .......                                         [  2%]
oggm/tests/test_graphics.py ...................X                              [  9%]
oggm/tests/test_minimal.py ...                                                [ 10%]
oggm/tests/test_models.py ..........................sss.......ssss..s.ss..sss [ 27%]
sss..sss                                                                      [ 29%]
oggm/tests/test_numerics.py .sssssssssss.ssss...s..ss.s                       [ 39%]
oggm/tests/test_prepro.py .................s........................s........ [ 56%]
........s....s............                                                    [ 64%]
oggm/tests/test_shop.py .......                                               [ 67%]
oggm/tests/test_utils.py .................................................... [ 84%]
ss.ss..sssss.ssssss..sss...s.ss.ss.ss..                                       [ 97%]
oggm/tests/test_workflow.py ssssss                                            [100%]

================================= warnings summary ==================================
(warnings are mostly ok)
======== 223 passed, 73 skipped, 1 xpassed, 9 warnings in 771.11s (0:12:51) =========

You can safely ignore deprecation warnings and other messages (if any), as long as the tests end without errors.

This runs a minimal suite of tests. If you want to run the entire test suite (including graphics and slow running tests), type:

pytest --pyargs oggm --run-slow --mpl

Congrats, you are now set-up for the Getting started section!

Installation troubleshooting

We try to do our best to avoid issues, but experience shows that the installation of the necessary packages can be difficult. Typical errors are often related to the pyproj, fiona and GDAL packages, which are heavy and (for pyproj) have changed a lot in the recent past and are prone to platform specific errors.

If the tests don’t pass, a diagnostic of which package creates the errors might be necessary. Errors like segmentation fault or Proj Error are frequent and point to errors in upstream packages, rarely in OGGM itself.

If you are having troubles, installing the packages manually from a fresh environment might help. At the time of writing (13.06.2020), creating an environment from this environment.yml file used to work (see the conda docs for more information about how to create an environment from a yml file):

name: oggm_env
channels:
  - conda-forge
dependencies:
  - python=3.7
  - jupyter
  - jupyterlab
  - numpy=1.16.5
  - scipy=1.4.1
  - pandas=0.25.3
  - shapely
  - matplotlib
  - Pillow
  - netcdf4=1.5.3
  - scikit-image
  - scikit-learn
  - configobj
  - xarray
  - pytest
  - dask
  - bottleneck
  - pyproj=2.2.2
  - cartopy=0.17.0
  - geopandas=0.7.0
  - rasterio=1.1.2
  - descartes
  - seaborn
  - pytables=3.6.1
  - pip
  - pip:
    - joblib
    - progressbar2
    - motionless
    - git+https://github.com/fmaussion/salem.git
    - git+https://github.com/retostauffer/python-colorspace
    - git+https://github.com/OGGM/pytest-mpl
    - git+https://github.com/OGGM/oggm

Install with pyenv (Linux)

Note

We recommend our users to use conda instead of pip, because of the ease of installation with conda. If you are familiar with pip and pyenv, the instructions below work as well: as of Sept 2020 (and thanks to pip wheels), a pyenv installation is possible without major issue on Debian/Ubuntu/Mint systems.

Linux packages

Run the following commands to install required linux packages.

For building python and stuff:

$ sudo apt-get install --no-install-recommends make build-essential git \
    libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget \
    curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
    libffi-dev liblzma-dev`

For NetCDF and HDF:

$ sudo apt-get install netcdf-bin ncview hdf5-tools libhdf5-dev

Pyenv and pyenv-virtualenv

Install pyenv and create a new virtual environment with a recent python version (3.7+) using pyenv-virtualenv.

Python packages

Be sure to be on the working environment:

$ pyenv activate oggm_env

Update pip (important!):

$ pip install --upgrade pip

Install some packages one by one:

$ pip install numpy scipy pandas shapely matplotlib pyproj \
    rasterio Pillow geopandas netcdf4 scikit-image configobj joblib \
    xarray progressbar2 pytest motionless dask bottleneck toolz descartes \
    tables

A pinning of the NetCDF4 package to 1.3.1 might be necessary on some systems (related issue).

Finally, install the pytest-mpl OGGM fork, salem and python-colorspace libraries:

$ pip install git+https://github.com/OGGM/pytest-mpl.git
$ pip install git+https://github.com/fmaussion/salem.git
$ pip install git+https://github.com/retostauffer/python-colorspace.git

OGGM and tests

Refer to Install OGGM itself above.

Install a minimal OGGM environment

If you plan to use only the numerical core of OGGM (that is, for idealized simulations or teaching), you can skip many dependencies and only install this shorter list:

  • numpy
  • scipy
  • pandas
  • matplotlib
  • shapely
  • requests
  • configobj
  • netcdf4
  • xarray
  • pytables

Installing them with pip or conda should be much easier.

Running the tests in this minimal environment works the same. Simply run from a terminal:

pytest --pyargs oggm

The number of tests will be much smaller!