Skip to content

Tutorial for using ESMValTool on Gadi

What is ESMValTool?

The Earth System Model Evaluation Tool (ESMValTool) is a climate model diagnostics and evaluation software package to better understand the causes and effects of model biases and inter-model spread.

Support Level: Supported on Gadi, but not owned by ACCESS-NRI

ESMValTool is a community-developed climate model diagnostics and evaluation software package. While ACCESS-NRI does not own the code, it actively supports the use of ESMValTool software on Gadi. ACCESS-NRI provides access to the latest version of ESMValTool via the xp65 access-med conda environment for Model Evaluation on Gadi.

The ESMValTool mainly focuses on evaluating results from the Coupled Model Intercomparison Project (CMIP) ensemble.

For more information, refer to the official ESMValTool documentation.

Using ESMValTool on Gadi

ESMValTool is provided through the xp65 access-med conda environment for Model Evaluation on Gadi.
ACCESS-NRI plans to routinely run benchmarks and comparisons of CMIP submissions for ACCESS models, as well as providing support to run ESMValTool recipes on Gadi.


To run ESMValTool recipes, you need to be a member of the following NCI projects:

  • xp65, ct11, fs38, oi10, rr3, al33, rt52, zz93 and qv56.

Running ESMValTool recipes

To load the the access-med conda environment, execute the following commands:

    module use /g/data/xp65/public/modules
    module load conda/access-med

To list which ESMValTool recipes are available on Gadi, run:

    esmvaltool recipes list

To find out details of a specific recipe_name.yml, execute:

esmvaltool recipes show recipe_name.yml

To execute recipe_name.yml and automatically download the required climate data to the default directory, run:

esmvaltool run examples/recipe_python.yml --search_esgf=when_missing
The --search_esgf=when_missing option tells ESMValTool to search for and download the necessary climate data files from Earth System Grid Federation (ESGF), if they cannot be found locally.

ESMValTool recipe examples

A list of ESMValTool recipes available on Gadi can be found on the ACCESS-NRI MED ESMValTool Workflow GitHub repository. Some example recipes are provided below:


To get help running your ESMValTool recipe on Gadi, you can submit an issue on the ESMValTool-Workflow GitHub repository or ask for help on the ACCESS-Hive Forum.

General ESMValTool support (i.e. non-specific to Gadi) can be found on the ESMValTool Discussions page, where users can also post technical questions on the ESMValTool installation, application and development.

Recipes and diagnostics

Contacts for specific diagnostic sets are the authors listed in the source code and corresponding recipe and diagnostic documentation.

The current status of ESMValTool recipes for the xp65 conda environment on Gadi is available here


The ESMValTool is released under the Apache License, version 2.0. Citation of the ESMValTool paper (“Software Documentation Paper”) is requested upon use, along with the software DOI for ESMValTool (doi:10.5281/zenodo.3401363) and ESMValCore (doi:10.5281/zenodo.3387139) together with the version:

Righi, M., Andela, B., Eyring, V., Lauer, A., Predoi, V., Schlund, M., Vegas-Regidor, J., Bock, L., Brötz, B., de Mora, L., Diblen, F., Dreyer, L., Drost, N., Earnshaw, P., Hassler, B., Koldunov, N., Little, B., Loosveldt Tomas, S., and Zimmermann, K.: Earth System Model Evaluation Tool (ESMValTool) v2.0 – technical overview, Geosci. Model Dev., 13, 1179–1199,, 2020.

Besides the above citation, users are asked to register any journal articles (or other scientific documents) that use the software at the ESMValTool webpage ( Citing the Software Documentation Paper and registering your paper(s) will serve to document the scientific impact of the Software, which is important for securing future funding. You should consider this an obligation if you have taken advantage of the ESMValTool, which represents the end product of considerable effort by the development team.

Last update: September 21, 2023