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 (or pixi as an alternative — see Installation with pixi)
• Git
• VSCode (or any other IDE)
• Java

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:

For Intel/AMD processorsFor ARM processors

• 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

Installation with pixi (Alternative)

pixi is a modern, fast package manager built on the conda ecosystem. It offers faster installation using a single cross-platform lock file (pixi.lock).

Install pixi

Follow the pixi installation guide for your OS, or run:

Linux / macOSWindows

curl -fsSL https://pixi.sh/install.sh | sh

Use the installer available in the pixi installation guide or execute the following in the powershell:

iwr -useb https://pixi.sh/install.ps1 | iex

Verify the installation with:

pixi --version

Clone the Repository

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

Install Dependencies

pixi reads the pixi.toml file at the root of the repository and automatically resolves and locks all dependencies into pixi.lock.

pixi install

This typically completes in a few minutes and creates a local .pixi/ environment — no global environment management required.

Enable Prompt Indicator (Recommended)

By default pixi does not modify your terminal prompt. Enable it once globally so your prompt shows the active environment — similar to conda:

pixi config set shell.change-ps1 true --global

After this, pixi shell will show (pypsa-earth) in your prompt:

(pypsa-earth) user@machine ~/pypsa-earth $

To check if you are inside a pixi shell at any time:

echo $PIXI_IN_SHELL   # prints 1 if inside, empty if not

Run Commands

There are two ways to use the environment:

Option 1 — pixi shell (interactive use, closest to conda):

pixi shell            # enter the environment
snakemake --version   # run commands normally, no prefix needed
exit                  # leave the environment (never use conda deactivate)

Option 2 — pixi run (scripts and CI):

pixi run snakemake --version   # run a single command inside the environment
pixi run make test

Remove the Environment

To remove the installed environment (e.g. to free up disk space or reinstall cleanly):

pixi clean

This deletes .pixi/envs/ but keeps pixi.toml and pixi.lock intact. To reinstall:

pixi install

Note

The pixi.lock file pins all package versions across platforms (Linux, macOS, Windows) in a single file, ensuring reproducibility without needing separate lock files per OS.

Do not use conda deactivate inside pixi shell

If you are inside a pixi shell, always exit using exit or Ctrl+D. Running conda deactivate inside a pixi shell will crash conda because pixi uses conda's environment variables internally in a way that conda's deactivation logic cannot handle.

Project-scoped environment

Unlike conda, pixi environments are local to the project directory (.pixi/envs/). pixi run and pixi shell only work when invoked from the pypsa-earth root directory.

To use the environment from a different directory (e.g., a separate notebooks repo), you can source the environment into your current shell:

# run from within the pypsa-earth directory
eval "$(pixi shell-hook)"

For Jupyter, register the environment as a named kernel once:

pixi run install-kernel

After this, any Jupyter session can select the pypsa-earth kernel regardless of the working directory.

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:

• CBC
• GLPK and [WinGLPK]
• HiGHS

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:

   • Windows
   • Linux
   • MacOS

   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.