The following sections will guide you through the installation of CLIMADA and its dependencies.


CLIMADA has a complicated set of dependencies that cannot be installed with pip alone. Please follow the installation instructions carefully! We recommend to use Anaconda for creating a suitable software environment to execute CLIMADA.

All following instructions should work on any operating system (OS) that is supported by Anaconda, including in particular: Windows, macOS, and Linux.


When mentioning the terms “terminal” or “command line” in the following, we are referring to the “Terminal” apps on macOS or Linux and the “Anaconda Prompt” on Windows.


  • Make sure you are using the latest version of your OS. Install any outstanding updates.

  • Free up at least 10 GB of free storage space on your machine. Anaconda and the CLIMADA dependencies will require around 5 GB of free space, and you will need at least that much additional space for storing the input and output data of CLIMADA.

  • Ensure a stable internet connection for the installation procedure. All dependencies will be downloaded from the internet. Do not use a metered, mobile connection!

  • Install Anaconda, following the installation instructions for your OS.


If you need help with the vocabulary used on this page, refer to the Glossary.

Decide on Your Entry Level!#

Depening on your level of expertise, we provide two different approaches:

  • If you have never worked with a command line, or if you just want to give CLIMADA a try, follow the simple instructions.

  • If you want to use the very latest development version of CLIMADA or even develop new CLIMADA code, follow the advanced instructions.

Both approaches are not mutually exclusive. After successful installation, you may switch your setup at any time.

Notes on the CLIMADA Petals Package#

CLIMADA is divided into two packages, CLIMADA Core (climada_python) and CLIMADA Petals (climada_petals). The Core contains all the modules necessary for probabilistic impact, averted damage, uncertainty and forecast calculations. Data for hazard, exposures and impact functions can be obtained from the CLIMADA Data API. Hazard and Exposures subclasses are included as demonstrators only.


CLIMADA Petals is not a standalone module and requires CLIMADA Core to be installed!

CLIMADA Petals contains all the modules for generating data (e.g., TC_Surge, WildFire, OpenStreeMap, …). New modules are developed and tested here. Some data created with modules from Petals is available to download from the Data API. This works with just CLIMADA Core installed. CLIMADA Petals can be used to generate additional data of this type, or to have a look at the tutorials for all data types available from the API.

Both installation approaches mentioned above support CLIMADA Petals. If you are unsure whether you need Petals, you can install the Core first and later add Petals in both approaches.

Simple Instructions#

These instructions will install the most recent stable version of CLIMADA without cloning its repository.

  1. Open the command line. Create a new conda environment with CLIMADA by executing

    conda create -n climada_env -c conda-forge climada
  2. Activate the environment:

    conda activate climada_env

    You should now see (climada_env) appear in the beginning of your command prompt. This means the environment is activated.

  3. Verify that everything is installed correctly by executing a single test:

    python -m unittest climada.engine.test.test_impact

    Executing CLIMADA for the first time will take some time because it will generate a directory tree in your home/user directory. After a while, some text should appear in your terminal. In the end, you should see an “Ok”. If so, great! You are good to go.

  4. Optional: Install CLIMADA Petals into the environment:

    conda install -n climada_env -c conda-forge climada-petals

Advanced Instructions#

For advanced Python users or developers of CLIMADA, we recommed cloning the CLIMADA repository and installing the package from source.

  1. If you are using a Linux OS, make sure you have git installed (Windows and macOS users are good to go once Anaconda is installed). On Ubuntu and Debian, you may use APT:

    apt update
    apt install git

    Both commands will probably require administrator rights, which can be enabled by prepending sudo.

  2. Create a workspace directory. To make sure that your user can manipulate it without special privileges, use a subdirectory of your user/home directory. Do not use a directory that is synchronized by cloud storage systems like OneDrive, iCloud or Polybox!

  3. Open the command line and navigate to the workspace directory you created using cd. Replace <path/to/workspace> with the path of the directory that contains the workspace folder:

    cd <path/to/workspace>
  4. Clone CLIMADA from its GitHub repository. Enter the directory and check out the branch of your choice. The latest development version will be available under the branch develop.

    git clone
    cd climada_python
    git checkout develop
  5. Create an Anaconda environment called climada_env for installing CLIMADA. Use the default environment specs in env_climada.yml to create it. Then activate the environment:

    conda env create -n climada_env -f requirements/env_climada.yml
    conda activate climada_env
  6. Install the local CLIMADA source files as Python package using pip:

    python -m pip install -e ./


    Using a path ./ (referring to the path you are currently located at) will instruct pip to install the local files instead of downloading the module from the internet. The -e (for “editable”) option further instructs pip to link to the source files instead of copying them during installation. This means that any changes to the source files will have immediate effects in your environment, and re-installing the module is never required.

  7. Verify that everything is installed correctly by executing a single test:

    python -m unittest climada.engine.test.test_impact

    Executing CLIMADA for the first time will take some time because it will generate a directory tree in your home/user directory. If this test passes, great! You are good to go.

Install Developer Dependencies (Optional)#

Building the documentation and running the entire test suite of CLIMADA requires additional dependencies which are not installed by default. They are also not needed for using CLIMADA. However, if you want to develop CLIMADA, we recommend you install them.

With the climada_env activated, enter the workspace directory and then the CLIMADA repository as above. Then, add the dev extra specification to the pip install command (mind the quotation marks, and see also pip install examples):

python -m pip install -e "./[dev]"

The CLIMADA Python package defines the following extras:


Includes Dependencies…


for building documentation


for running and evaluating tests


combination of doc and test

For executing the pre-defined test scripts in exactly the same way as they are executed by the automated CI pipeline, you will need make to be installed. On macOS and on Linux it is pre-installed. On Windows, it can easily be installed with conda:

conda install -n climada_env make

Instructions for running the test scripts can be found in the Testing and CI Guide.

Install CLIMADA Petals (Optional)#

If you are unsure whether you need Petals, see the notes above.

To install CLIMADA Petals, we assume you have already installed CLIMADA Core with the advanced instructions above.

  1. Open the command line and navigate to the workspace directory.

  2. Clone CLIMADA Petals from its repository. Enter the directory and check out the branch of your choice. The latest development version will be available under the branch develop.

    git clone
    cd climada_petals
    git checkout develop
  3. Update the Anaconda environment with the specifications from Petals and activate it:

    conda env update -n climada_env -f requirements/env_climada.yml
    conda env update -n climada_env -f requirements/env_developer.yml
    conda activate climada_env
  4. Install the CLIMADA Petals package:

    python -m pip install -e ./

Apps for Programming in Python#

To work with CLIMADA, you will need an application that supports Jupyter Notebooks. There are plugins available for nearly every code editor or IDE, but if you are unsure about which to choose, we recommend JupyterLab, Visual Studio Code or Spyder.


  1. Install JupyterLab into the Anaconda environment:

    conda install -n climada_env -c conda-forge jupyterlab
  2. Make sure that the climada_env is activated (see above) and then start JupyterLab:

    conda env activate climada_env

    JupyterLab will open in a new window of your default browser.

Visual Studio Code (VSCode)#

Basic Setup#

  1. Download and install VSCode following the instructions on

  2. Install the Python and Jupyter extensions. In the left sidebar, select the “Extensions” symbol, enter “Python” in the search bar and click Install next to the “Python” extension. Repeat this process for “Jupyter”.

  3. Open a Jupyter Notebook or create a new one. On the top right, click on Select Kernel, select Python Environments… and then choose the Python interpreter from the climada_env.

See the VSCode docs on Python and Jupyter Notebooks for further information.

Workspace Setup#

Setting up a workspace for the CLIMADA source code is only available for advanced installations.

  1. Open a new VSCode window. Below Start, click Open…, select the climada_python repository folder in your workspace directory, and click on Open on the bottom right.

  2. Click File > Save Workspace As… and store the workspace settings file next to (not in!) the climada_python folder. This will enable you to load the workspace and all its specific settings in one go.

  3. Open the Command Palette by clicking View > Command Palette or by using the shortcut keys Ctrl+Shift+P (Windows, Linux) / Cmd+Shift+P (macOS). Start typing “Python: Select Interpreter” and select it from the dropdown menu. If prompted, choose the option to set the interpreter for the workspace, not just the current folder. Then, choose the Python interpreter from the climada_env.

For further information, refer to the VSCode docs on Workspaces.

Test Explorer Setup#

After you set up a workspace, you might want to configure the test explorer for easily running the CLIMADA test suite within VSCode.


Please install the additional test dependencies before proceeding.

  1. In the left sidebar, select the “Testing” symbol, and click on Configure Python Tests.

  2. Select “pytest” as test framework and then select climada as the directory containing the test files.

  3. Select “Testing” in the Activity Bar on the left or through View > Testing. The “Test Explorer” in the left sidebar will display the tree structure of modules, files, test classes and individual tests. You can run individual tests or test subtrees by clicking the Play buttons next to them.

  4. By default, the test explorer will show test output for failed tests when you click on them. To view the logs for any test, click on View > Output, and select “Python Test Log” from the dropdown menu in the view that just opened. If there are errors during test discovery, you can see what’s wrong in the “Python” output.

For further information, see the VSCode docs on Python Testing.


Installing Spyder into the existing Anaconda environment for CLIMADA might fail depending on the exact versions of dependencies installed. Therefore, we recommend installing Spyder in a separate environment, and then connecting it to a kernel in the original climada_env.

  1. Follow the Spyder installation instructions. Make sure you install it with conda!

  2. Check the version of the Spyder kernel in the new environment:

    conda env export -n spyder-env | grep spyder-kernels

    This will return a line like this:

    - spyder-kernels=X.Y.Z=<hash>

    Copy the part spyder-kernels=X.Y.Z (until the second =) and paste it into the following command to install the same kernel version into the climada_env:

    conda install -n climada_env spyder-kernels=X.Y.Z
  3. Obtain the path to the Python interpreter of your climada_env. Execute the following commands:

    conda activate climada_env
    python -c "import sys; print(sys.executable)"

    Copy the resulting path.

  4. Open Spyder. You can do so from the Anaconda Navigator, or by activating the new environment and launching it through the command line:

    conda activate spyder-env
  5. Set the Python interpreter used by Spyder to the one of climada_env. Select Preferences > Python Interpreter > Use the following interpreter and paste the iterpreter path you copied from the climada_env.


Answers to frequently asked questions.

Updating CLIMADA#

We recommend keeping CLIMADA up-to-date. To update, follow the instructions based on your installation type:

  • Simple Instructions: Update CLIMADA using conda:

    conda update -n climada_env -c conda-forge climada
  • Advanced Instructions: Move into your local CLIMADA repository and pull the latest version of your respective branch:

    cd <path/to/workspace>/climada_python
    git pull

    Then, update the environment:

    conda env update -n climada_env -f requirements/env_climada.yml
    conda env update -n climada_env -f requirements/env_developer.yml

    The same instructions apply for CLIMADA Petals.

Installing More Packages#

You might use CLIMADA in code that requires more packages than the ones readily available in the CLIMADA Anaconda environment. If so, prefer installing these packages via Anaconda, and only rely on pip if that fails. The default channels of Anaconda sometimes contain outdated versions. Therefore, use the conda-forge channel:

conda install -n climada_env -c conda-forge <package>

Only if the desired package (version) is not available, go for pip:

conda activate climada_env
python -m pip install <package>

Verifying Your Installation#

If you followed the installation instructions, you already executed a single unit test. This test, however, will not cover all issues that could occur within your installation setup. If you are unsure if everything works as intended, try running all unit tests. This is only available for advanced setups! Move into the CLIMADA repository, activate the environment and then execute the tests:

cd <path/to/workspace>/climada_python
conda activate climada_env
python -m unittest discover -s climada -p "test*.py"

Error: ModuleNotFoundError#

Something is wrong with the environment you are using. After each of the following steps, check if the problem is solved, and only continue if it is not:

  1. Make sure you are working in the CLIMADA environment:

    conda activate climada_env
  2. Update the conda environment and CLIMADA.

  3. Anaconda will notify you if it is not up-to-date. In this case, follow its instructions to update it. Then, repeat the last step and update the environment and CLIMADA (again).

  4. Install the missing package manually. Follow the instructions for installing more packages.

  5. If you reached this point, something is severely broken. The last course of action is to delete your CLIMADA environment:

    conda deactivate
    conda env remove -n climada_env

    Now repeat the installation process.

  6. Still no good? Please raise an issue on GitHub to get help.

Logging Configuration#

Climada makes use of the standard logging package. By default, the “climada”-Logger is detached from logging.root, logging to stdout with the level set to WARNING.

If you prefer another logging configuration, e.g., for using Climada embedded in another application, you can opt out of the default pre-configuration by setting the config value for logging.climada_style to false in the configuration file climada.conf.

Changing the logging level can be done in multiple ways:

  • Adjust the configuration file climada.conf by setting a the value of the global.log_level property. This only has an effect if the logging.climada_style is set to true though.

  • Set a global logging level in your Python script:

    import logging
    logging.getLogger('climada').setLevel(logging.ERROR)  # to silence all warnings
  • Set a local logging level in a context manager:

    from climada.util import log_level
    with log_level(level="INFO"):
        # This also emits all info log messages
    # Default logging level again

All three approaches can also be combined.

Mamba Instead of Anaconda#

If you prefer using Mamba, you should be able to simply replace all conda commands with mamba. Note that we can only provide limited support for Mamba installations!

Error: operation not permitted#

Conda might report a permission error on macOS Mojave. Carefully follow these instructions:

No impf_TC Column in GeoDataFrame#

This may happen when a demo file from CLIMADA was not updated after the change in the impact function naming pattern from if_ to impf_ when CLIMADA v2.2.0 was released. Execute

conda activate climada_env
python -c "import climada; climada.setup_climada_data(reload=True)"

The What Now? (Glossary)#

You might have become confused about all the names thrown at you. Let’s clear that up:

Terminal, Command Line

A text-only program for interacting with your computer (the old fashioned way).

Anaconda, conda

The program that installs all requirements and creates a suitable environment for CLIMADA.

Environment (Programming)

A setup where only a specific set of modules and programs can interact. This is especially useful if you want to install programs with mutually incompatible requirements.


The Python package installer.


A popular version control software for programming code (or any text-based set of files).


A website that publicly hosts git repositories.

git Repository

A collection of files and their entire revision/version history, managed by git.


The process and command (git clone) for downloading a git repository.


Integrated Development Environment. A fancy source code editor tailored for software development and engineering.