Setup

Authors
Affiliations

Marius Pille

Berlin Institute of Health at Charité University Medicine

Leon Martin

Berlin Institute of Health at Charité University Medicine

Leon Stefanovski

Charité University Medicine Berlin

This page explains how to set up your environment to run the workshop notebooks. Two options are available: Docker (recommended, no Python setup needed) or a local install via uv.

Option B: Local install with uv

Use this option if you prefer to work directly on your machine or want to install your own packages alongside TVBO.

1. Install uv

uv is a fast Python package manager that also handles Python installation.

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

Restart your terminal afterwards (or run source ~/.bashrc / source ~/.zshrc).

Open PowerShell and run:

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

Restart PowerShell afterwards.

If you get an execution policy error when running scripts later (e.g. activating the venv), allow signed local scripts for your user once:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Verify:

uv --version

2. Install Python

TVBO requires Python 3.11 or later. Install it with uv:

uv python install 3.12

3. Create an environment

mkdir tvbo-workshop
cd tvbo-workshop
uv venv --python 3.12

Activate it:

source .venv/bin/activate
.venv\Scripts\activate

Your prompt will show (.venv) when the environment is active.

4. Install TVBO + TVB-Optim

uv pip install "tvbo[all]"

This installs TVBO and the TVB simulator backend used in the workshop.

5. Verify

Paste this directly into your activated shell (PowerShell, bash, or zsh):

python -c "from tvbo import Dynamics, SimulationExperiment; print('Ready!')"

Troubleshooting

Problem Fix
uv: command not found Restart your terminal; on macOS/Linux check that ~/.local/bin is on your PATH
No module named tvbo Activate the virtual environment first — you should see (.venv) in your prompt
Python version error Run uv python install 3.12, then uv venv --python 3.12
Windows execution policy error Open PowerShell as Administrator and run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Docker: port already in use Change the host port: docker run -p 8889:8888 ... and open localhost:8889

Option C: Run in Google Colab

Run the notebooks in your browser. No install required.

Step 1. Open a notebook in Colab:

  • Click the Open in Colab button at the top of any notebook page on this site, or
  • Download the .ipynb from the workshop repository and upload it in Colab via File → Upload notebook.

Step 2. Run the first cell. It detects Colab and installs the dependencies. If a later cell fails with ModuleNotFoundError, install the missing package in a new cell:

!pip install "tvbo[all]"   # or whichever package is missing

Option D: Run on EBRAINS

EBRAINS provides JupyterLab through the Collaboratory. It works, but RAM is limited.

Step 1. Log in at lab.ebrains.eu and start a JupyterLab session.

Step 2. Open a terminal and install TVBO into a user environment:

pip install --user "tvbo[all]"

Step 3. Upload the notebook you want to run and execute it. If you hit memory errors or import conflicts, switch to one of the other options.

Back to top