JupyterHub Basics

This page covers the fundamentals you need to work in a UZH JupyterHub deployment — from launching your server to managing files and Python environments.

The JupyterLab interface

JupyterLab is the web-based environment you see after logging in. It provides a file browser, notebook editor, terminal, and more.

Key areas of the UI:

Area	Description
Left sidebar	File browser, running terminals & kernels, table of contents
Main work area	Open notebooks, scripts, terminals — arrange in tabs or splits
Status bar	Kernel name and status, line/column position
Launcher	Opens a new notebook, console, or terminal

Using Git in JupyterLab

You can use Git directly from the terminal or via the built-in Git extension.

Open a terminal from the Launcher and use standard git commands, or click the Git icon in the left sidebar for a visual interface.

Do not store credentials (or, in fact, anything really secret) on a JupyterHub server. Your team-mates (on a group-server), teachers, IT staff, will all have access to your files as one and the same user, jovyan. We recommend short-lived github tokens.

Python virtual environments and kernels

Each notebook runs against a kernel — a running Python process. The kernels available in the Launcher correspond to Python environments installed on your server.

⚠️ What survives a server restart — and what doesn’t

Location	Survives restart?
Files and conda environments under `/home/jovyan`	✅ Yes — this is a persistent volume
Packages installed into the base conda environment	❌ No — the base env lives in the container image and is reset on restart

Do not rely on conda install or pip install in the base environment for anything you need to keep. Always create a dedicated conda environment in your home directory instead.

Creating a custom conda kernel

Open a terminal from the Launcher and run:

# 1. Create a new conda environment in your home directory
conda create -y -n myenv python=3.11

# 2. Activate it
conda activate myenv

# 3. Install your packages
conda install -y numpy pandas matplotlib   # add whatever you need

# 4. Register the environment as a Jupyter kernel
conda install -y ipykernel
python -m ipykernel install --user --name myenv --display-name "My Environment"

Refresh the Launcher (or reload the page) — My Environment will appear as a new kernel option.

Where does the environment live?
By default, conda create places the environment under ~/.conda/envs/myenv, which is inside /home/jovyan — your persistent home directory. The kernel registration is stored under ~/.local/share/jupyter/kernels/myenv, also inside /home/jovyan. Both survive server restarts.

To make your environment reproducible, export it to a file:

conda activate myenv
conda env export > environment.yml

Anyone (including your future self after a lost environment) can recreate it with:

conda env create -n myenv -f environment.yml
python -m ipykernel install --user --name myenv --display-name "My Environment"

👩‍🎓 Participants: Course environments are pre-configured by your teacher. You typically do not need to create kernels yourself unless your course instructs you to. If you do, always use a dedicated conda environment (as shown above) — never install packages into the base environment.

👩‍🏫 Owners / Coaches: Pre-installed kernels are baked into the server Docker image. To add a kernel for all students, add the environment to the image and rebuild. See the deployment documentation for details. You can provide an environment.yml to students so they can recreate the exact environment locally or in a fresh server.

UZH persistent volumes

Each JupyterHub deployment mounts two persistent shared volumes:

One at /home/jovyan, your personal space. Your notebooks and data files are stored here and survive server restarts.
One at /home/jovyan/shared, shared with the whole course and read-only.

Key points:

/home/jovyan — your personal persistent directory. Files here are not lost when your server stops.
/home/jovyan/shared – this is a symbolic link to /home/shared, a read-only file-system.
/tmp — temporary storage, cleared on restart. Do not store important work here.
The volume size is fixed per deployment. If you run out of space, contact your course administrator.

👩‍🎓 Participants: Always save your work under /home/jovyan. If you use the terminal to download large datasets, prefer /tmp to avoid filling the shared volume.

👩‍🏫 Owners / Coaches: The volume size is configured in the Terraform deployment (values.tfvars). A PersistentVolumeClaim (PVC) is provisioned per user. Storage reclamation on user removal is manual — check with the ZI Cloud team.

Writing to the shared volume is possible by uploading to the Azure storage account. A link will be provided to you by ZI.