---
file_format: mystnb
kernelspec:
  name: python3
  display_name: Python 3
---

# Set up Python

When using Python, we strongly recommend creating isolated environments rather than relying on any pre-installed Python installations.
This provides the greatest flexibility when it comes to using different interpreters and package versions.

Several modern tools can be used to create isolated Python environments. The most common ones are:

| Tool | When it shines | Why you might pick it |
|------|----------------|-----------------------|
| [micromamba](https://mamba.readthedocs.io/en/) | Scientific computing, mixed Python / C libraries | Excellent support for compiled scientific packages |
| [uv](https://docs.astral.sh/uv/) | Projects that only depend on pure‑Python wheels | Extremely fast resolver and installer (very lightweight) |
| [Pixi](https://pixi.prefix.dev/latest/) | Complex, hybrid projects that need reproducible builds | Strong focus on reproducible workflows |

Our focus here is micromamba, which offers the broadest compatibility with the scientific Python ecosystem while remaining lightweight and easy to install.

## Installation

On Linux and macOS you can install `micromamba` with:

```bash
"${SHELL}" <(curl -L micro.mamba.pm/install.sh)
```

Please refer to the [official documentation](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html) for more details and different installation methods.

## Creating an environment

The recommended way to create an environment is to specify the environment name, Python version and dependencies in an `environment.yaml`:

```yaml
name: my_env
channels:
  - conda-forge
dependencies:
  - python=3.12
  - matplotlib
  - numpy
  - scipy
  - eccodes
  - pip:
    - gribscan
```

Now you can create the environment by running:

```bash
micromamba env create -f environment.yaml
```

This approach makes it easy to share, reproduce, and recreate your environment across different machines.

```{admonition} Take-home messages
:class: note
An example `environment.yaml` used at our hackathons can be [found here](https://github.com/digital-earths-global-hackathon/tools/blob/main/python_envs/environment_2026.yaml).
```

## Managing environments

`micromamba` allows you to manage several virtual environments.
You can show the existing environments by running:

```bash
micromamba env list
```

The currently active environment is marked with an `*`.

You can switch between environments with:

```bash
micromamba activate <env_name>
```

Because the usage of `micromamba` is equivalent to that of `conda`, you can refer to the [conda documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) for more information about managing environments.

## Using an environment as IPython kernel

To use your custom environment in Jupyter notebooks (e.g. via the [DKRZ JupyterHub](https://jupyterhub.dkrz.de)), you need to register it as a [kernel](https://ipython.readthedocs.io/en/stable/install/kernel_install.html) --- a bridge between Jupyter and your Python interpreter.

You can install your own Python environments as a kernel by running the following command:

```bash
micromamba activate my_env
python3 -m ipykernel install --user --name my_env
```

```{admonition} Info
:class: info
The ``--user`` flag installs the kernel in the user's local directory (safe and doesn't require admin rights)
```

Afterwards, you should be able to select your environment when creating a new Jupyter notebook in the web browser.