Skip to content

Installation

Before installing PyPSA-Earth on your computer, it's crucial to ensure that your system meets the necessary hardware and software requirements. The following sections outline the prerequisites in terms of hardware and software. Additionally, detailed installation guidelines for required software tools will be provided, followed by step-by-step instructions for installing PyPSA-Earth.

Hardware Requirements

Ensure that your system meets the minimum hardware specifications to run PyPSA-Earth effectively. Recommended hardware specifications may include:

  • 8-16 GB RAM and adequate CPU (at least 2-cores)
  • Storage (HDD/SSD) capacity depends on the region of interest:
  • Africa model requires 40 GB
  • The world requires ~250 GB
  • A single country requires between 1-10 GB
  • Tutorial requires just below 2 GB

Thus, considering all required software tools, at least 40 GB of storage space is recommended.

Software Prerequisites

Prior to installing PyPSA-Earth, you'll need to ensure the following software tools are installed and configured on your system:

Miniconda

To use packages in python, it is highly recommended to use a conda package manager, such as miniconda. You may check if conda is already installed on your system with:

conda --version

If conda is not installed, follow the miniconda installation guide. For more information on how to install conda and work with it you can look into Software Hints.

Git

Git is a free open-source tool that facilitates tracking changes in the code development and enables coordinating the parallel software development between many developers. Download and install git to your system using the following link. It is highly recommended to learn the git basics.

VSCode

In order to write and debug python code, you need an Integrated Development Environment (IDE) that is a software used to write code. We recommend Visual Studio Code, which is freely available online and provides an easy-to-use interface with Git. Obviously, any alternatives like PyCharm or Sublime will work as well.

Java

PyPSA-Earth currently needs Java redistribution to work properly. To check if Java is still installed you can request its version from a terminal:

java --version

The expected output should resemble the following:

java version "1.8.0_341"
Java(TM) SE Runtime Environment (build 1.8.0_341-b10)
Java HotSpot(TM) 64-Bit Server VM (build 25.341-b10, mixed mode)

In case you don't have Java, you have to install it. We recommend:

  • Windows Users: Install it directly from the official website. Download and install JDK 21 or JDK 17.
  • Linux or macOS Users: You can install openjdk directly in your conda environment:
mamba install -c conda-forge openjdk

Installation with Conda/Mamba

Clone the Repository

Note

In order to work with the provided Jupyter notebooks in the documentation repository, it is recommended to follow the folder structure suggested in Notebooks.

First of all, clone the PyPSA-Earth repository using the version control system git. The path to the directory into which the git repository is cloned must not have any spaces. The following commands can be executed in command prompt of miniconda, terminal of VSCode, or in Git Bash.

git clone https://github.com/pypsa-meets-earth/pypsa-earth.git
cd pypsa-earth

Note

Make sure that you are in the pypsa-earth root directory. If you are not sure, you can check it with pwd command in Linux or MacOS, or cd command in Windows. If you are in the wrong directory, you can navigate to the pypsa-earth root directory with cd path/to/pypsa-earth command.

Install Dependencies

PyPSA-Earth relies on a set of other Python packages to function.

The python package requirements are located in the envs/environment.yaml file. We install only mamba in the conda base environment to accelerate the installation. Please keep the base environment always clean, meaning don't install anything there! It will allow to ensure compatibility of all the packages needed to work with PyPSA-Earth model.

There are also regularly updated locked environment files for each platform generated with conda-lock to ensure reproducibility. Choose the correct file for your platform:

  • Linux: envs/linux-64.lock.yaml
  • macOS: envs/osx-64.lock.yaml
  • Windows: envs/win-64.lock.yaml
  • macOS (Apple Silicon): envs/osx-arm64.lock.yaml
  • Linux (ARM): Currently not supported via lock files; requires building certain packages, such as PySCIPOpt, from source

We recommend using these locked files for a stable environment.

Note

You can check and verify your platform with conda info.

conda install -c conda-forge mamba

mamba env create -f envs/linux-64.lock.yaml  # select the appropriate file for your platform

conda activate pypsa-earth

Environment installation with mamba usually takes about 10-20 minutes. Note please that activation is local to the currently open shell. Every time you open a new terminal window, pypsa-earth environment should be activated again to supply the workflow with all the dependencies it needs.

In case mamba did not work for you, you might want to try conda instead:

conda env create -f envs/linux-64.lock.yaml

conda activate pypsa-earth

If a pre-generated lock file is not available for your platform (e.g., aarch64, ARM Mac, etc.), you can simply install the environment using the environment.yaml file, which is not locked and may lead to compatibility issues.

conda install -c conda-forge mamba

mamba env create -f envs/environment.yaml

Generating the Lock Files (Advanced Users)

If you wish to generate lock-files for your platform, you can use the following commands:

  1. Ensure conda-lock is installed:
conda install conda-lock -c conda-forge
  1. Generate lock files for target platforms:
conda-lock lock -p <your-platform> -k env -f envs/environment.yaml

For platform codes, refer to the conda-lock documentation or use conda info to determine your platform.

Pro Tip

For more information on how to install conda and work with it you can look into Software Hints.

To confirm the installation, run the following command in the activated environment:

snakemake --version

Solver Installation

An optimization solver is needed to solve the mathematical problem that is built with the automated workflow of PyPSA-Earth. With the goal of supporting completely open source initiative, we focus on relying on Open-Source solvers, such as:

To further improve performances, commercial solvers like:

  • Gurobi (the Gurobi package is pre-installed in the environment, but you must obtain and activate your own license; see the Gurobi documentation for details)
  • CPLEX

(both commercial licenses with free academic options) can also be used.

Note

glpk, gurobi, and highs are installed automatically with the environment. However, solving capabilities of glpk are limited. To run the model with high temporal and spatial resolution, it is recommended to use cplex, gurobi, or highs.

Install Jupyter Lab

We use Jupyter notebooks to share examples on how to use the model and analyse the results. VSCode supports working with Jupyter Notebooks natively. In case you are using a different IDE and don't have Jupyter notebooks pre-installed you can install jupyter lab (new jupyter notebooks) with the ipython kernel installation and test if your jupyter lab works:

ipython kernel install --user --name=pypsa-earth
jupyter lab

Alternate installation with Docker

This is an alternative way to create a development environment for PyPSA-Earth. This method is useful for users who are not familiar with programming or Python, or who do not want to install Python on their local machine. It uses Docker containers to create a development environment for PyPSA-Earth.

This section provides a step-by-step guide on how to set up and use Docker containers to run PyPSA-Earth.

  1. Install Docker: Follow the instructions for your operating system:

    Important Note

    Ensure Docker is installed on your system.

  2. You can use the link here to install Visual Studio Code on your operating system. Ensure to select the most compatible file for your operating system.

  3. Install GitHub Desktop for your OS here.

  4. Clone the repository:

    • Open GitHub Desktop.
    • Click on File in the top left corner.
    • Click on Clone Repository.

    • Paste the following URL in the URL field:

      https://github.com/pypsa-meets-earth/pypsa-earth.git

    • Click on Clone.

    • Choose the location where you want to save the repository.
    • Click on Current Branch: main and select devContainers.
    • Click on Open in Visual Studio Code.

    The repository will be cloned to your local machine.

  5. Rebuild and open in a container:

    • Open the repository in VSCode.
    • Click on the icon in the far bottom left corner of the VSCode window.
    • Click on Reopen in Container.
    • Wait for the container to build and open the repository in the container.

The environment will be ready for use. You can now run PyPSA-Earth in the container.