Hinzufügen weiterer Python-Bibliotheken

Obwohl Pythons „Batteries included“-Philosophie bedeutet, dass ihr mit der Standardinstallation von Python bereits eine Menge machen könnt, wird unweigerlich die Situation kommen, in der ihr eine Funktionalität benötigt, die nicht in Python enthalten ist.

Wenn ihr ein Modul eines Drittanbieters benötigt, das nicht für eure Plattform vorgefertigt ist, müsst ihr dessen Quell-Distribution verwenden. Dies bringt jedoch zwei Probleme mit sich:

1. Um die Quell-Distribution zu installieren, müsst ihr sie finden und herunterladen.

2. Es werden bestimmte Python-Pfade und Berechtigungen eures Systems erwartet.

Python bietet pip als aktuelle Lösung für beide Probleme an. pip versucht, das Modul im Python Package Index (PyPI) zu finden, lädt es und alle Abhängigkeiten herunter und kümmert sich um die Installation. Ihr könnt auch pypi.org direkt aufrufen und nach Paketen zu suchen oder die Pakete nach Kategorien filtern.

Warnung

Installiert niemals irgendetwas mit pip in das globale Python, auch nicht mit dem --user Flag. Verwendet immer venv. So vermeidet ihr, dass eure Python-Installation mit Bibliotheken verunreinigt wird, die ihr installiert und dann vergesst. Jedes Mal, wenn ihr etwas Neues machen müsst, solltet ihr eine neue virtuelle Umgebung erstellen. Damit vermeidet ihr auch Bibliothekskonflikte zwischen verschiedenen Projekten.

Tipp

wir empfehlen euch, pip so zu konfigurieren, dass es nicht möglich ist, Python-Pakete global zu installieren. Hierfür könnt ihr folgendes in eure ~/.config/pip/pip.conf eintragen:

[global]
require-virtualenv = true

venv

Eine virtuelle Umgebung (virtualenv) ist eine in sich geschlossene Verzeichnisstruktur, die sowohl eine Installation von Python als auch die zusätzlichen Pakete enthält. Da die gesamte Python-Umgebung in diesem Verzeichnis enthalten ist, können die dort installierten Bibliotheken und Module nicht mit denen im Hauptsystem oder in anderen virtuellen Umgebungen kollidieren, so dass verschiedene Anwendungen unterschiedliche Versionen von Python und seinen Paketen verwenden können. Das Erstellen und Verwenden einer virtuellen Umgebung erfolgt in zwei Schritten:

1. Zuerst erstellen wir ein Projektverzeichnis und dann darin die virtuelle Umgebung:

   Linux/macOS

   $ mkdir myproj
   $ cd myproj
   $ python3 -m venv .venv
   

   Windows

   > mkdir myproj
   > cd myproj
   > py -m venv .venv
   

   Hiermit wird die Umgebung mit Python und pip in einem Verzeichnis namens .venv erstellt.

2. Anschließend könnt ihr diese Umgebung aktivieren, sodass beim nächsten Aufruf von python das Python aus eurer neuen Umgebung verwendet wird:

   Linux/macOS

   $ . .venv/bin/activate
   

   Windows

   > .venv\Scripts\activate
   

3. Python-Pakete nur für diese virtuelle Umgebung installieren, z.B. die beliebte pandas-Bibliothek:

   Linux/macOS

   (.venv) $ python -m pip install pandas
   

   Windows

   (.venv) > python.exe -m pip install pandas
   

4. Wenn ihr eure Arbeit an diesem Projekt beenden wollt, könnt ihr die virtuelle Umgebung wieder deaktivieren mit

   Linux/macOS

   (.venv) $ deactivate
   

   Windows

   (.venv) > deactivate
   

Siehe auch

• Virtual Environments and Packages

pip

Die grundlegende Syntax von pip ist recht einfach:

(.venv) $ python -m pip install pandas

Wenn ihr eine bestimmte Version eines Pakets angeben wollt, könnt ihr die Versionsnummern einfach anhängen:

(.venv) $ python -m pip install pandas==2.2.2

oder

(.venv) $ python -m pip install "pandas>=2"

Proxy-Server

Um Python-Pakete über einen Proxy-Server zu installieren, könnt ihr folgendes eingeben: python -m pip install --proxy http://USER_NAME:{PASSWORD}@PROXYSERVER_NAME:PORT PKG_NAME

Ihr könnt den Proxy-Server auch dauerhaft als Umgebungsvariable speichern:

Linux

z.B. in der ~/.bashrc mit:

$ export HTTP_PROXY=http://{USER_NAME}:{PASSWORD}@{PROXYSERVER_NAME}:{PORT}

Windows

Fügt die folgende Zeile den Umgebungsvariablen hinzu:

> set HTTP_PROXY={PROXYSERVER_NAME}:{PORT}

Festschreiben …

… von Python

Im Gegensatz zu Anwendungen unterstützen unsere Pakete normalerweise mehr als eine Python-Version. Dennoch fügen wir auch bei Paketen üblicherweise die aktuelle Standard-Version in .python-version hinzu:

.python-version

3.14

Das Schöne daran ist, dass wir die gleiche Datei in GitHub Actions als Eingabe für setup-python verwenden können:

.github/workflows/ci.yml

jobs:
  docs:
    name: Build docs and check links
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      with:
        persist-credentials: false
    - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
      with:
        # Keep in sync with .readthedocs.yaml
        python-version-file: .python-version

In unseren GitLab CI/CD-Pipelines verwenden wir jedoch requires-python aus der pyproject.toml-Datei, um Docker-Container mit der passenden Python-Version zu bauen.

… von Paketen

Für eine stabile Umgebung ist es sinnvoll, die exakten Varianten der Abhängigkeiten festzuschreiben.

Tipp

In keinem unserer Bibliotheksprojekte passiert so viel, dass die Git-Historie vorwiegend aus Updates bestehen sollte. Lediglich bei Problemen schränken wir dort die zu verwendenden Versionsnummern ein. Bei Anwendungen (engl.: Apps) schreiben wir die Versionsnummern jedoch fest.

Um für unsere Anwendungen die exakte Variante festzuschreiben und plattformübergreifende Lock-Dateien zu erhalten, verwenden wir üblicherweise uv. Zudem unterstützt uns uv bei reproduzierbaren Python-Umgebungen.

Pakete können jedoch auch mit pip≥26.1 festgeschrieben werden:

$ python -m pip install --upgrade pip
$ python -m pip --version

PEP 751 legte das Format für die pylock.toml-Datei fest, die mit folgendem Aufruf erzeugt werden kann, z. B. mit:

$ python -m pip lock -e . -o pylock.prod.toml

Alternativ kann auch aus einer requirements.txt-Datei eine pylock.toml-Datei generiert werden:

$ python -m pip lock -r requirements.txt -o pylock.prod.toml

Warnung

In beiden Fällen werden jedoch nur die Pakete für die aktuelle Plattform- und Python-Version festgeschrieben.

Tipp

Wenn pip nicht das einzige verfügbare Tool ist, stellt die plattformübergreifende Ausgabe von uv export den reibungsloseren Weg dar.

Anschließend können die in der pylock.NAME.toml festgeschriebenen Pakete in einer anderen Umgebung installiert werden mit:

$ python -m pip install -r pylock.prod.toml --no-deps

--no-deps

sorgt dafür, dass auch die transitiven Abhängigkeiten nicht zusätzlich zur pylock.NAME.toml-Datei aufgelöst werden.

Siehe auch

• pip lock

• pylock.toml Specification

uv

uv vereinfacht das Erstellen einer initialen Projektstruktur und die Verwaltung eurer Abhängigkeiten.

Bemerkung

Viele Coding-Agenten verwenden üblicherweise pip, wenn Pakete installiert oder Skripte ausgeführt werden sollen. Daher müssen wir sie zunächst so konfigurieren, dass sie uv verwenden:

AGENTS.md

- Use `uv` to manage Python environments and dependencies.
- Use `uv run` to execute Python scripts and commands.
- Don't edit `pyproject.toml` directly. Instead, use `uv add` and `uv add --dev` to manage dependencies.

Siehe auch

• uv

Installation

uv hängt nicht von Python ab. Vorkompilierte, eigenständige Binärdateien können auf Linux, macOS und Windows installiert werden:

Linux/macOS

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

Windows

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

uv aktualisiert sich bei dieser Installation regelmäßig selbst.

Automatische Shell-Vervollständigung

Um die automatische Shell-Vervollständigung für uv-Befehle zu aktivieren, führt jeweils einen der folgenden Schritte aus:

Linux/macOS

Bestimmt eure Shell, z.B. mit echo $SHELL, dann führt einen der folgenden Befehle aus:

$ echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
$ echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
$ echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish
$ echo 'eval (uv generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv

$ echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc
$ echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc
$ echo 'uvx --generate-shell-completion fish | source' > ~/.config/fish/completions/uvx.fish
$ echo 'eval (uvx --generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv

Windows

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

Startet dann die Shell neu oder ruft source mit eurer Shell-Konfigurationsdatei ein.

Update

Ihr könnt uv ganz einfach aktualisieren mit:

$ uv self update
info: Checking for updates...
success: Upgraded uv from v0.8.12 to v0.8.13! https://github.com/astral-sh/uv/releases/tag/0.8.13

Python-Installation

Mit uv python install lässt sich die aktuelle Python-Version installieren. Alternativ lässt sich auch eine spezifische Version installieren mit uv python install 3.14. Es lassen sich jedoch nicht nur ältere CPython-Versionen installieren, sondern z.B. auch PyPy mit uv python install pypy@3.12 oder Free-threaded Python mit uv python install --python-preference only-managed 3.14t. Die bereits installierten Python-Versionen erhaltet ihr mit uv python list. Eine installierte Python-Version könnt ihr aufrufen mit uv run --python 3.14 python.

Projektstruktur erstellen

Je nachdem, ob ihr eine Bibliothek oder Anwendung erstellen wollt, kann uv eine passende Projektstruktur erstellen.

Abhängigkeiten installieren

Mit uv sync --frozen könnt ihr die Abhängigkeiten eures Projekts installieren in den in der uv.lock-Datei exakt festgeschriebenen Varianten.

Siehe auch

• uv.lock-Datei

• Reproduzieren der Python-Umgebung

Mit uv pip install --pylock pylock.NAME.toml könnt ihr die Abhängigkeiten auch von einer bestehenden pylock.NAME.toml-Datei installieren.

Abhängigkeiten hinzufügen

Mit uv add PACKAGE könnt ihr eurem Projekt weitere Abhängigkeiten hinzufügen. Dabei wird das hinzugefügte Paket sowohl im dependencies-Abschnitt der pyproject.toml-Datei hinzugefügt, wie auch die exakte Vatiante in die uv.lock-Datei geschrieben.