Feedback on Installation Procedure

[gustavo-dias]

My observations on the installation guide provided here. In what follows, let CME mean conda/mamba environment.

1. Section "Java"

It is not clear if Java is to be installed directly in the user's (local) machine or inside a CME. The guide instructs the user to check if Java is available running:

java --version

without mentioning whether or not any particular CME must be active. If not, it recommends installing it running:

mamba install -c conda-forge openjdk

which suggests that Java must be installed in a CME; however it does not mention which one.

Remarks:

• At this point the user hasn't been instructed yet to install conda, mamba or even create, activate any particular CME.

• If one installs Java as the command suggests e.g. in PyPSA-Earth's CME, it makes changes as the summary below depicts:
  Install: 10 packages
  Change: 14 packages
  Upgrade: 51 packages
  Downgrade: 1 packages

Which may cause post-installation compatibility issues.

Feedback:

• Make it clear where to install:

  • Directly in the user's (local) machine or;
  • In a CME, mentioning which one.

• If (b) is the case and PyPSA-Earth's CME is the proper CME, I would place the Java installation section after the "Install with Conda/Mamba" section (where the user effectively creates said environment).

2. Section "Install Dependencies"

It recommends to install miniconda first and then install mamba inside conda's base environment. Besides mamba being faster than conda itself, there might be other hard technical requirement to do so (in the past, perhaps), but mamba is a drop in for miniconda (i.e. a direct alternative), and should/can be installed directly in the user's (local) machine.

Feedback:

• If there is no hard technical requirement to maintain this, choose one over the other and adjust the guide accordingly.
• Instruct the user to install PyPSA-Earth's CME using the lock files only (no reason to mess with environment.yaml as a beginner).

3. Further ideas/feedback

• Have a (bash) script to formally check the installation (i.e. give the user a mean to check if the installation was successful).

• Perhaps remove old content like the Youtube videos [2], [3]: outdated material may hinder more than help newcomers.

• Provide a more straight forward step-by-step installation tutorial like the example below (for Linux).

Example Linux Installation Instructions (click to expand).

---

Performed on Ubuntu 24.04.4 LTS as of 2026/05/13 ¹.

1. Update apt (recommended not required):

   ~$ sudo apt update
   

2. Install Git:

   ~$ sudo apt install git
   

3. Install and setup VSCode:

   • Download deb file from the website;
   • Install as:

     ~/path/to/deb/file$ sudo apt install ./<vscode_deb_filename>.deb
     

   • Open VSCode, navigate to tab Extensions (left side menu), search and install Python and Jupyter extensions.

4. Install Mamba (extracted from the website):

   • Download the installer; run either:

     ~/path/to/download/dir$ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
     

     or

     ~/path/to/download/dir$ wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
     

   • then execute the script:

     ~/path/to/download/dir$ bash Miniforge3-$(uname)-$(uname -m).sh
     

5. Fork PyPSA-Earth repo into your github account [how-to].

6. Clone forked repo to disk [see how-to above]:

   ~/path/to/installation/dir$ git clone <url_of_forked_repo>.git
   

7. Create the mamba environment with the lock yaml file:

   ~/path/to/installation/dir/pypsa-earth$ mamba env create -f ./envs/linux-64.lock.yaml
   

8. Install java JDK 17 or 21 in your (local) machine:

   • Run:

     ~$ sudo apt install openjdk-21-jdk
     

   • Check installation:

     ~$ java --version
     

Footnotes

1. I managed to run the tutorial with no errors using this installation procedure. ↩

[gustavo-dias]

Hi @GbotemiB, as mentioned previously, here is my feedback on the installation procedure. Happy to discuss! Perhaps @kwaku-duah is also interested in the topic.

[GbotemiB]

Hi @gustavo-dias, thank you for the feedback.

Regarding your feedback;

1. Here’s the flow: there are preceding software prerequisites that require you to have those software installed, and all of them have links. Prerequisites sites mean you have to have them installed. The list contains conda, git, vscode, and java. For miniconda vs conda, we advise miniconda as it’s lighter compared to Anaconda itself, which both still provide access to use conda/mamba.
2. We can safely remove mamba and default the instructions to use conda (in the past, conda was slower). We already have it documented instructing users to use a lock file. We can add more information to make this clearer.
3. A bash script might introduce complexity. To confirm installation, we ask the user to run snakemake —version. We probably need to make it more visible. Regarding the old YouTube videos, the documentation might have evolved over time, but I think users can benefit from understanding how to interact with the package. The example for installation on Linux might not be that straightforward for installing all the packages, which is why we attach the direct links in the docs. Referring to each package installation page is the most straightforward way to keep up with updated packages.

[gustavo-dias]

Alright, @GbotemiB , I hope it was useful!