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 any platform.
Complete beginners should get familiar with Python and its packaging ecosystem before trying to install and run OGGM.
For most users we recommend following the steps here to install Python and the package dependencies with the conda package manager. Linux or Debian users and people with experience with pip can follow the specific instructions here to install with virtualenv.
If you are using a Linux Mint distribution you may want to test if you are affected by the pyproj bug described here
- Standard SciPy stack:
- Configuration file parsing tool:
- GIS tools:
- Other libraries:
- progressbar2 (displays the download progress)
- bottleneck (speeds up xarray operations)
- dask (works nicely with xarray)
Install with conda (all platforms)¶
This is the recommended way to install OGGM.
You should have a recent version of git and 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).
Linux users should install a couple of Linux packages (not all of them are required but it’s good to have them anyway):
$ sudo apt-get install build-essential liblapack-dev gfortran libproj-dev git gdal-bin libgdal-dev netcdf-bin ncview python-netcdf4 ttf-bitstream-vera
We recommend to create a specific environment for OGGM. In a terminal window, type:
conda create --name oggm_env python=3.X
3.X is the Python version shipped with conda (currently 3.6).
You can of course use any other name for your environment.
Don’t forget to activate it before going on:
source activate oggm_env
Install the packages from the conda-forge and
conda install -c oggm -c conda-forge oggm-deps
oggm-deps package is a “meta package”. It does not contain any code but
will install all the packages OGGM needs automatically.
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 (see an example here). We strongly recommend to always use the the conda-forge channel for your installation.
You might consider setting conda-forge (and
oggm) per default, as
suggested on their documentation page:
conda config --add channels conda-forge conda config --add channels oggm conda install <package-name>
conda install -c conda-forge ipython jupyter
If you are using conda, you can install OGGM as a normal conda package:
conda install -c oggm -c conda-forge oggm
If you are using pip, you can install OGGM from PyPI:
pip install oggm
In this case you will be able to use the model but you cannot change its code. If you want to explore the code or participate in its development, we recommend to clone the git repository (or your own fork, see also Contributing to OGGM):
git clone https://github.com/OGGM/oggm.git
Then go to the project root directory:
And install OGGM in development mode (this is valid for pip or conda environments):
pip install -e .
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.
You are almost there! The last step is to check if everything works as
expected. From the
oggm directory, type:
The tests can run for a couple of minutes. If everything worked fine, you should see something like:
=============================== test session starts =============================== platform linux -- Python 3.5.2, pytest-3.3.1, py-1.5.2, pluggy-0.6.0 Matplotlib: 2.1.1 Freetype: 2.6.1 rootdir: plugins: mpl-0.9 collected 164 items oggm/tests/test_benchmarks.py ... [ 1%] oggm/tests/test_graphics.py ................... [ 13%] oggm/tests/test_models.py ................sss.ss.....sssssss [ 34%] oggm/tests/test_numerics.py .ssssssssssssssss [ 44%] oggm/tests/test_prepro.py .......s........................s..s....... [ 70%] oggm/tests/test_utils.py .....................sss.s.sss.sssss..ss. [ 95%] oggm/tests/test_workflow.py sssssss [100%] ==================== 112 passed, 52 skipped in 187.35 seconds =====================
You can safely ignore deprecation warnings and other DLL messages as long as the tests end without errors.
Congrats, you are now set-up for the Getting started section!
Install with virtualenv (Linux/Debian)¶
The installation with virtualenv and pip requires a few more steps than with conda. Unless you have a good reason to install by this route, installing with conda is probably what you want to do.
The instructions below are for Debian / Ubuntu / Mint systems only!
Run the following commands to install required packages.
For the build:
$ sudo apt-get install build-essential python-pip liblapack-dev gfortran libproj-dev python-setuptools
$ sudo apt-get install tk-dev python3-tk python3-dev
$ sudo apt-get install gdal-bin libgdal-dev python-gdal
$ sudo apt-get install netcdf-bin ncview python-netcdf4
Next follow these steps to set up a virtual environment.
Install extensions to virtualenv:
$ sudo apt-get install virtualenvwrapper
Reload your profile:
$ source /etc/profile
Make a new environment, for example called
oggm_env, with Python 3:
$ mkvirtualenv oggm_env -p /usr/bin/python3
(Further details can be found for example in this tutorial.)
Be sure to be on the working environment:
$ workon oggm_env
Update pip (important!):
$ pip install --upgrade pip
Install some packages one by one:
$ pip install numpy scipy pandas shapely matplotlib
Installing GDAL is not so straightforward. First, check which version of GDAL is installed on your Linux system:
$ gdal-config --version
The package version (e.g.
2.3.1, …) should match
that of the Python package you want to install. For example, if the Linux
GDAL version is
2.2.0, install the latest corresponding Python version.
The following command works on any system and automatically gets the right version:
$ pip install gdal=="$(gdal-config --version)" --install-option="build_ext" --install-option="$(gdal-config --cflags | sed 's/-I/--include-dirs=/')"
Fiona also builds upon GDAL, so let’s compile it the same way:
$ pip install fiona --install-option="build_ext" --install-option="$(gdal-config --cflags | sed 's/-I/--include-dirs=/')"
(Details can be found in this blog post.)
Now install further dependencies:
$ pip install pyproj rasterio Pillow geopandas netcdf4 scikit-image configobj joblib xarray boto3 progressbar2 pytest motionless dask bottleneck
Finally, install the salem library:
$ pip install git+https://github.com/fmaussion/salem.git