Python environments

• Slides

Installing Python

You can install Python on Windows using the official installer. On Mac, you can use Homebrew. However, you will need different versions of Python for different analyses, so it’s a good idea to use conda for installing Python.

Python comes as a set of basic packages and on top of that you install additional packages. Installing a package is not so simple as packages depend on other packages. Conda handles these dependencies very efficient.

Why use Python environments?

For the spatial, imaging, and Python trainings we work with Python environments because they allow to:

• Install packages and their dependencies easily.
• Create isolated Python environments: you can maintain multiple environments, each with its own Python version and its own set of packages. These environments are fully separated, so installations in one environment do not affect the others.
• Share environments via XML files to ensure reproducibility.

The video below focuses on conda environments, but the explanation applies to any Python environment, whether it is a virtual environment or a conda environment. For the spatial trainings, we now use uv to create a virtual environment (see the next sections).

Types of Python environments

The two main ways of creating Python environments are conda and virtual environments. Virtual environments are created by the python -m venv command or by uv, a more recent tool for creating Python environments extremely fast. Uv creates virtual environments, which are similar to conda environments but not identical.

Both conda and virtual environments are folders on your computer that:

• contain a Python interpreter
• run a specific version of Python (that is different from your main Python)
• contain specific versions of Python packages
• isolate this Python and these packages from your global Python installation
• provide an environment with the correct Python + packages for reproducing a specific analysis

But conda and virtual environments differ in what they can contain.

A virtual environment is a folder on your computer that contains:

• a bin or Scripts folder with a Python installation
• a Lib folder with Python packages

It’s Python only, it cannot install non-Python dependencies. If your analysis needs C/C++ libraries, R, or system tools, you need to install those globally.

A conda environment is a folder on your computer that contains:

• a bin folder with a Python and a C/C++ compiler installation
• a lib folder with Python and non-Python packages

It supports R, C/C++ libraries, system tools… So it can install Python and non-Python dependencies, making it ideal for analyses that need more than just Python, but it’s relatively slow to create and solve dependencies.

Install uv

• Installation instructions for uv

Uv creates a virtual environment. The positive side is that it’s extremely fast (faster than conda) to create an environment, it can solve dependencies in a faster way than python -m venv. The downside is that it cannot install anything that is non-Python, because it fetches all packages from PyPI (Python only repository).

In short, on Windows open powershell and run the following command:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

On Mac open a terminal and run the following command:

curl -LsSf https://astral.sh/uv/install.sh | sh

Close powershell/terminal, reopen it and run the following code:

uv --version

If uv was installed you should see the version that was installed on your computer.

Homework for everyone:

• Install uv on your computer

Create a virtual environment with uv using a toml file

• .toml file to install the environment for the Python trainings

You don’t have to activate / deactivate a virtual environment.

Homework for everyone:

• Create a folder called jupyter_notebooks (anywhere you want on your computer)
• Put the .toml file in this folder
• In powershell/terminal use cd to go to this jupyter_notebooks folder and run the following code to create the environment:

uv sync

Running this command will:

• Generate a hidden folder .venv/ to jupyter_notebooks folder
• Install Python
• Install all dependencies
• Generate a uv.lock file

Create a virtual environment with uv using a requirements file

Homework only for people who will follow the spatial omics summer school:

• Close git bash (or terminal) and reopen it again
• In git bash (or terminal) use cd to go to the targeted_transcriptomics_analysis folder that was created in the spatial folder by git (use tab autocompletion to avoid typos!)

cd ..
cd ..
cd spatial
cd targeted_transcriptomics_analysis

• Create the virtual environment (make sure you have uv installed!) by running the following code:

bash create_env.sh
ls -al

This should show a list that contains a hidden folder called .venv that was created by uv in the targeted_transcriptomics_analysis folder.

! In the video the spatial folder is in my home folder, for everyone working on Windows the spatial folder should be on the C-drive (in C:/spatial) to avoid issues with long path names.

! On Mac the names of the folders in the .venv folder might be different.

Everyone can stop here: we are not going to use conda environments in the Python trainings, so you can skip the rest of this topic!

—————————————————————————————————————————

Install conda

• Installation instructions for miniconda

In Windows you use the anaconda prompt for executing conda commands, on Mac you use a terminal.

Create a conda environment

Create a conda environment via (the -n option allows to specify a name for the environment):

conda create -n name_env

Activate and deactivate a conda environment

If you want to use a conda environment, you first have to activate it via:

conda activate name_env

If you’re finished using the environment, you deactivate it via:

conda deactivate

Install packages in a conda environment

Install Python packages via:

conda install name_pkg

In conda, packages are installed from channels, which are essentially online repositories that host and manage packages. Conda’s default channel is managed by Anaconda, but other channels exist like conda-forge.

Check which channels are supported in your environment via:

conda config --show channels

Check what is used as the default channel via:

conda config --show defaults-channels

Add a channel to your environment via:

conda config --env --add channels name_channel

Create a conda environment from a .yml file

A .yml file is a text file with a specific format that contains all the instructions for creating a conda environment with a specific version of Python and a set of Python packages.

To create an environment from a .yml file via (the –file option refers to the .yml file):

conda env create --file environment.yml

Recap: overview of important conda commands