This lesson is being piloted (Beta version)



Teaching: 10 min
Exercises: 10 min
  • What are the prerequisites for installing ESMValTool?

  • How do I confirm that the installation was successful?

  • Install ESMValTool

  • Demonstrate that the installation was successful


The instructions help with the installation of ESMValTool on operating systems like Linux/MacOSX/Windows. We use the Conda package manager to install the ESMValTool. Other installation methods are also available; they can be found in the documentation. We will first install Conda, and then ESMValTool. We end this chapter by testing that the installation was successful.

Before we begin, here are all the possible ways in which you can use ESMValTool depending on your level of expertise or involvement with ESMvalTool and associated software such as GitHub and Conda.

  1. If you have access to a server where ESMValTool is already installed as a module, for e.g., the CEDA JASMIN server, you can simply load the module with the following:
    module load esmvaltool

    After loading esmvaltool, we can start using ESMValTool. Please see the next lesson.

  2. If you would like to install ESMValTool as a conda package, then this lesson will tell you how!
  3. If you would like to start experimenting with existing diagnostics or contributing to ESMvalTool, please see the instructions for source installation in the lesson Development and contribution and in the documentation.

Install ESMValTool on Windows

ESMValTool does not directly support Windows, but successful usage has been reported through the Windows Subsystem for Linux(WSL), available in Windows 10. To install the WSL please follow the instructions on the Windows Documentation page. After installing the WSL, installation can be done using the same instructions for Linux/MacOSX.

Install ESMValTool on Linux/MacOSX

Install Conda

ESMValTool is distributed using Conda. Let’s check if we already have Conda installed by running:

conda list

If conda is installed, we will see a list of packages. We recommend updating conda before esmvaltool installation. To do so, run:

conda update -n base conda

If conda is not installed, we can use Miniconda minimal installer for conda. We recommend a Python 3 based installer. For more information about installing conda, see the conda installation documentation.

To install conda on Linux or MacOSX, follow the instructions below:

  1. Please download Miniconda3 at the miniconda page. If you have problems with the 64 bit version in the next step(s) you can alternatively try a 32 bit version.

  2. Next, run the installer from the place where you downloaded it:

    On Linux:


    On MacOSX:

  3. Follow the instructions in the installer. The defaults should normally suffice.

  4. You will need to restart your terminal for the changes to have effect.

  5. Verify you have a working conda installation by listing all installed packages

    conda list

Install Julia

Some ESMValTool diagnostics are written in the Julia programming language. If you want a full installation of ESMValTool including Julia diagnostics, you need to make sure Julia is installed before installing ESMValTool.

In this tutorial, we will not use Julia, but for reference, we have listed the steps to install Julia below. Complete instructions for installing Julia can be found on the Julia installation page.

Julia installation instructions

First, open a bash terminal and create a directory to install Julia in and cd into it

mkdir ~/julia
cd ~/julia

Next, to download and extract the file julia-1.0.5-linux-x86_64.tar.gz, you can use the following commands::

tar -xvzf julia-1.0.5-linux-x86\_64.tar.gz

This will extract the files to a directory named ~/julia/julia-1.0.5. To run Julia, you need to add the full path of Julia’s bin folder to PATH environment variable. To do this, you can edit the ~/.bashrc (or ~/.bash_profile) file. Open the file in a text editor called nano:

nano ~/.bashrc

and add a new line as follows at the bottom of the file:

export PATH="$PATH:$HOME/julia/julia-1.0.5/bin"

Finally, for the settings to take effect, either reload your bash profile

source ~/.bashrc

(or source ~/.bash_profile), or close the bash terminal window and open a new one.

To check that the Julia executable can be found, run

which julia

to display the path to the Julia executable, it should be


To test that Julia is installed correctly, run


to start the interactive Julia interpreter. Press Ctrl+D to exit.

Install the ESMValTool package

The ESMValTool package contains diagnostics scripts in four languages: R, Python, Julia and NCL. This introduces a lot of dependencies, and therefore the installation can take quite long. It is, however, possible to install ‘subpackages’ for each of the languages. The following (sub)packages are available:

For the tutorial, we will use only Python diagnostics. Thus, to install the ESMValTool-python package, run

conda create -n esmvaltool -c conda-forge -c esmvalgroup esmvaltool-python

This will create a new Conda environment called esmvaltool, with the ESMValTool-Python package and all of its dependencies installed in it.

Common issues

  • Installation takes a long time
    • Downloads and compilations can take several minutes to complete, please be patient.
    • You might have bad luck and the dependencies can not be resolved at the moment, please try again later or raise an issue
    • If Solving environment takes more than 10 minutes, you may need to update conda: conda update -n base conda
    • You can help conda solve the environment by specifying the python version:
      conda create -n esmvaltool -c conda-forge -c esmvalgroup esmvaltool-python python=3.8
    • Note that on MacOSX, esmvaltool-python and esmvaltool-ncl only work with Python 3.7. Use python=3.7 instead of python=3.8.
  • If you have an old conda installation you could get a UnsatisfiableError message. Please install a newer version of conda and try again
  • Downloads fail due to company proxy, see conda docs how to resolve.

Test that the installation was successful

To test that the installation was successful, run

conda activate esmvaltool

to activate the conda environment called esmvaltool. In the shell prompt the active conda environment should have been changed from (base) to (esmvaltool).

Next, run

esmvaltool --help

to display the command line help.

Version of ESMValTool

Can you figure out which version of ESMValTool has been installed?


The esmvaltool --help command lists version as a command to get the version

In my case when I run

esmvaltool version

I get that my installed ESMValTool version is

ESMValCore: 2.0.0
ESMValTool: 2.0.0

Key Points

  • All the required packages can be installed using conda.

  • You can find more information about installation in the documentation.