Benutzerdefinierte Umgebung

Hinzufügen von Python-Paketen und Erstellen benutzerdefinierter Umgebungen¶

Viele häufig verwendete Python-Pakete sind in den bereitgestellten Images bereits vorinstalliert. Falls zusätzliche Pakete benötigt werden, können diese manuell installiert werden.

Die empfohlene Installationsmethode hängt von Ihrem Anwendungsfall ab:

• Um ein Paket zur Umgebung des aktuell ausgewählten Notebook-Kernels hinzuzufügen, verwenden Sie %pip install package_name in einem Notebook.
• Für projektspezifische Abhängigkeiten oder Pakete mit komplexen Anforderungen erstellen Sie eine eigene Conda-Umgebung oder eine virtuelle Umgebung (venv).
• Installieren oder aktualisieren Sie keine zentralen Jupyter-Pakete mit pip install --user. Pakete, die in Ihrem persistenten Home-Verzeichnis installiert werden, können die zentral verwalteten JupyterHub-Pakete überschreiben und Kompatibilitätsprobleme verursachen.

Zu den Kernpaketen von Jupyter gehören jupyterlab, notebook, jupyter-server, jupyter-server-proxy und jupyterhub.

Es gibt drei unterstützte Möglichkeiten, zusätzliche Python-Pakete hinzuzufügen:

1. Verwendung von Pip¶

Um ein Paket in der Umgebung zu installieren, die vom aktuell ausgewählten Notebook-Kernel verwendet wird, führen Sie den folgenden Befehl in einer Codezelle des Notebooks aus:

%pip install package_name

Der magische Befehl %pip führt pip in der Umgebung aus, die dem aktuellen Kernel zugeordnet ist. Im Standard-Python-Kernel ist diese Umgebung schreibgeschützt. Daher installiert pip stattdessen in Ihr Home-Verzeichnis unter ~/.local, was einer Installation mit --user entspricht. Diese Pakete bleiben nach einem Neustart des Servers erhalten und gelten für alle Notebooks mit dem Standard-Kernel. Möglicherweise müssen Sie den Kernel nach der Installation neu starten.

Diese Methode eignet sich für einfache Projektpakete. Für isolierte, reproduzierbare oder komplexere Umgebungen sollten Sie stattdessen eine dedizierte Conda-Umgebung oder eine venv verwenden.

2. Verwendung von Conda¶

Viele Standard-Systemverzeichnisse sind schreibgeschützt, weshalb eine direkte Installation von Paketen in die Basisumgebung (Base Environment) nicht möglich ist. Stattdessen kann eine neue Conda-Umgebung erstellt werden (siehe Anleitung unten), in der eigene Pakete installiert und verwaltet werden können.

Neue Conda-Umgebung als Kernel in JupyterHub erstellen¶

Voraussetzungen¶

Vor der Installation neuer Pakete muss die Shell für Conda initialisiert werden. Dieser Schritt stellt sicher, dass Conda-Befehle im Terminal ordnungsgemäß funktionieren. Öffnen Sie dazu ein Terminal und führen Sie die folgenden Befehle aus:

conda init
bash

Installation¶

Um eine neue Conda-Umgebung mit Python 3.11 und dem Paket pandas zu erstellen, sind die folgenden Schritte erforderlich. Das Paket ipykernel wird ebenfalls benötigt, um diese Umgebung als Kernel in Jupyter nutzen zu können.

1. Öffnen Sie ein Terminal in JupyterHub.
2. Erstellen Sie die Umgebung mit folgendem Befehl:

   conda create --name py311 python=3.11 ipykernel pandas -y
   

3. Aktivieren Sie die Umgebung:

   conda activate py311
   

4. Installieren Sie die Umgebung als Jupyter-Kernel, damit sie in Notebooks verwendet werden kann:

   python -m ipykernel install --user --name py311 --display-name "Python (py311)"
   

5. Laden Sie die JupyterHub-Seite neu.

Abschließende Schritte

Die neue Umgebung sollte nun als auswählbarer Kernel zur Verfügung stehen, wenn Sie ein neues Notebook öffnen oder erstellen.

Wichtige Hinweise:

• conda init ist nur einmalig erforderlich, um die Shell für Conda einzurichten.
• py311, pandas oder die Python-Version können durch einen gewünschten Umgebungsnamen, andere Pakete oder eine andere Python-Version ersetzt werden.
• Der Kernel-Name „Python (py311)“ ist die Bezeichnung, die in Jupyter bei der Auswahl des Kernels angezeigt wird und kann beliebig angepasst werden.

3. Verwendung von venv¶

Virtuelle Python-Umgebungen (venv) sind eine schlanke Alternative zu Conda-Umgebungen. Legen Sie sie in Ihrem Home-Verzeichnis an, damit sie einen Serverneustart überdauern:

1. Öffnen Sie ein Terminal in JupyterHub.
2. Erstellen und aktivieren Sie die Umgebung. Um zusätzlich die im Image vorinstallierten Pakete zu nutzen, ergänzen Sie den ersten Befehl um --system-site-packages:

   python -m venv ~/venvs/myenv
   source ~/venvs/myenv/bin/activate
   

3. Installieren Sie ipykernel und Ihre Pakete:

   pip install ipykernel package_name
   

4. Registrieren Sie die Umgebung als Jupyter-Kernel und deaktivieren Sie sie anschließend:

   python -m ipykernel install --user --name myenv --display-name "Python (myenv)"
   deactivate
   

5. Laden Sie die JupyterHub-Seite neu.

„Python (myenv)“ erscheint nun im Launcher und in der Kernel-Auswahl.

So entfernen Sie eine Umgebung wieder:

jupyter kernelspec uninstall -y myenv
rm -rf ~/venvs/myenv

Wichtige Hinweise:

• Eine venv greift weder auf die im Image vorinstallierten Pakete noch auf Pakete in ~/.local zu. In einer venv installierte Pakete können daher die zentral verwalteten Jupyter-Pakete nicht überschreiben.
• Eine mit --system-site-packages erstellte venv greift auch auf die vorinstallierten Pakete und auf Ihre Pakete in ~/.local zu. In der venv installierte Pakete haben dabei Vorrang.
• Virtuelle Umgebungen werden auf Ihr Speicherlimit im Home-Verzeichnis angerechnet.

Ausführen von Befehlen und GUI-Anwendungen im Terminal¶

Durch das Öffnen eines Terminals in JupyterHub können beliebige Befehle oder Skripte ausgeführt werden. Als Benutzer verfügen Sie über die Berechtigung, Dateien mit Ihren Benutzerrechten auszuführen.

JupyterHub.nrw stellt außerdem ein X11-Terminal (Konsole) bereit, das den Zugriff auf GUI-basierte Anwendungen ermöglicht. Dies ermöglicht die Ausführung von Anwendungen, die eine grafische Benutzeroberfläche erfordern, beispielsweise wissenschaftliche Software, Visualisierungs- oder Analysewerkzeuge.

Nützliche Links¶

• Pip Dokumentation (auf Englisch)
• Conda Dokumentation (auf Englisch)
• Conda: Arbeiten mit Umgebungen (auf Englisch)
• Python-venv-Dokumentation (auf Englisch)