Python-Projekte mit uv verwalten

01 — Ausgangspunkt

Warum uv?

Die Installation eines Python-Moduls ist an sich keine große Sache. Ein Kommando wie pip install requests reicht aus. Schwierig wird es erst, wenn Sie mehrere Projekte entwickeln, die unterschiedliche Module oder Modulversionen benötigen. Früher oder später ist nicht mehr klar, welches Script welche Voraussetzungen hat. Ein Update, das für Projekt A notwendig ist, kann Projekt B lahmlegen.

Virtual Environments lösen dieses Problem. Jedes Projekt erhält ein eigenes Verzeichnis mit den benötigten Modulen. Das funktioniert zuverlässig, verursacht aber zusätzliche Arbeit: Sie müssen das Environment einrichten, aktivieren, mit pip befüllen und die verwendeten Versionen dokumentieren. Bei der Weitergabe des Projekts müssen alle Schritte in der richtigen Reihenfolge wiederholt werden.

Genau hier setzt uv an. Das Programm übernimmt die Modulverwaltung und kümmert sich bei Bedarf auch um das Virtual Environment und um Python selbst. Intern ist uv in Rust programmiert. Das macht das Programm sehr schnell, ist aus Anwendersicht aber nebensächlich. Wichtiger ist, dass für viele alltägliche Aufgaben ein einziges Werkzeug genügt.

02 — Vorbereitung

Installation

uv wird unabhängig von Python installiert. Unter macOS gelingt das am einfachsten mit Homebrew:

brew install uv

Für Linux und macOS stellt das Projekt außerdem ein Installations-Script zur Verfügung. Laden Sie das Script herunter, sehen Sie es kurz an und führen Sie es anschließend aus:

curl -LsSf https://astral.sh/uv/install.sh -o uv_install.sh
less uv_install.sh
sh uv_install.sh

Unter Windows verwenden Sie PowerShell:

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

Testen Sie abschließend, ob uv gefunden wird:

uv --version

uv 0.11.26 (… 2026-06-30 …)

Die Versionsnummer entspricht dem Stand dieses Artikels. Das Projekt wird intensiv weiterentwickelt; auf Ihrem Rechner kann bereits eine neuere Version installiert sein.

03 — Anwendung

Das erste Projekt

Nehmen wir an, Sie möchten ein kleines Script schreiben, das das Modul requests benötigt. Die folgenden Kommandos richten ein neues Projekt ein, fügen das Modul hinzu und führen das Beispielprogramm aus:

uv init myproject
cd myproject
uv add requests
uv run main.py

uv init erzeugt unter anderem main.py, pyproject.toml und .gitignore. Beim ersten uv add richtet uv außerdem das Verzeichnis .venv mit dem Virtual Environment ein. Sie müssen dieses Environment nicht aktivieren. uv run sorgt automatisch dafür, dass das richtige Python und die richtigen Module zum Einsatz kommen.

Weitere Module fügen Sie ebenfalls mit uv add hinzu. Nicht mehr benötigte Module entfernen Sie mit uv remove:

uv add beautifulsoup4
uv remove requests

Für Entwicklungswerkzeuge gibt es eine eigene Gruppe:

uv add --dev pytest ruff
uv run pytest
uv run ruff check .

Wenn das Projekt eine bestimmte Python-Version voraussetzt, kann uv auch diese Version installieren und für das Projekt auswählen:

uv python install 3.13
uv python pin 3.13

Das zweite Kommando erzeugt die Datei .python-version. Damit ist dokumentiert, welche Python-Version während der Entwicklung verwendet wurde.

04 — Reproduzierbarkeit

pyproject.toml und uv.lock

uv speichert die direkten Projektabhängigkeiten in pyproject.toml. Die Datei uv.lock enthält zusätzlich die konkret ermittelten Versionen aller direkten und indirekten Abhängigkeiten. Beide Dateien gehören zusammen.

Wenn Sie das Projekt in ein Git-Repository aufnehmen oder an eine andere Person weitergeben, übertragen Sie daher neben dem Python-Code zumindest pyproject.toml, uv.lock, gegebenenfalls .python-version sowie .gitignore. Das Verzeichnis .venv geben Sie nicht weiter. Es lässt sich aus den Projektdateien neu erzeugen.

Auf einem anderen Rechner reichen im einfachsten Fall diese Kommandos:

git clone https://example.com/myproject.git
cd myproject
uv run main.py

Vor der Ausführung prüft uv den Projektzustand und installiert fehlende Module. In automatisierten Tests soll das Lockfile dabei nicht unbemerkt geändert werden. Verwenden Sie dort uv run --locked oder prüfen Sie es vorher:

uv lock --check
uv run --locked main.py

Die Kommandos brechen ab, wenn pyproject.toml und uv.lock nicht zueinander passen. Das ist ein nützliches Extra für CI-Jobs, für den Einstieg aber nicht zwingend erforderlich.

05 — Migration

Bestehende Projekte weiterverwenden

Sie müssen ein bestehendes Projekt nicht sofort auf pyproject.toml und uv.lock umstellen. uv kann auch mit einer herkömmlichen requirements.txt arbeiten:

uv venv
uv pip install -r requirements.txt

uv venv richtet das Virtual Environment ein. uv pip install verhält sich weitgehend wie pip install, arbeitet aber mit dem schnellen Paket- und Download-Cache von uv.

Diese Vorgehensweise ist eine gute Möglichkeit, uv schrittweise auszuprobieren. Wenn alles funktioniert, können Sie später entscheiden, ob Sie das Projekt vollständig auf die Projektverwaltung von uv umstellen.

06 — Programme

Python-Tools installieren

Viele Python-Pakete sind keine Module für den eigenen Code, sondern fertige Kommandozeilenprogramme. Beispiele sind httpie, ruff oder mkdocs. Solche Programme können Sie mit uv tool install unabhängig von einem Projekt installieren:

uv tool install httpie
http --version

Jedes Tool erhält eine eigene Umgebung. Abhängigkeitskonflikte zwischen verschiedenen Programmen werden dadurch vermieden. Mit uv tool dir ermitteln Sie, wo die Tool-Umgebungen gespeichert sind; uv tool dir --bin zeigt das Verzeichnis mit den ausführbaren Dateien.

Wenn Sie ein Programm nur ausprobieren oder einmalig ausführen möchten, ist uvx noch bequemer:

uvx ruff check .

uvx lädt ruff samt Abhängigkeiten in den Cache und führt das Programm aus. Eine dauerhafte Installation ist nicht erforderlich. Mit uv cache clean können Sie die zwischengespeicherten Dateien später löschen.

07 — Neuere Möglichkeit

Abhängigkeiten direkt im Script

Eine interessante Ergänzung sind Script-Metadaten gemäß PEP 723. Sie sind für kleine Scripts gedacht, für die ein komplettes Projektverzeichnis übertrieben wäre. uv kann die Metadaten erzeugen und verwalten:

uv init --script weather.py --python 3.13
uv add --script weather.py requests
uv run weather.py

Im Kopf der Datei entsteht dabei ein Kommentarblock:

# /// script
# requires-python = ">=3.13"
# dependencies = [
#   "requests",
# ]
# ///

Das Script enthält damit alle Informationen, die uv zur Ausführung benötigt. Sie können die einzelne Datei weitergeben; uv run weather.py richtet die passende Umgebung automatisch ein.

uv kann mittlerweile noch mehr, beispielsweise mehrere zusammengehörige Projekte in Workspaces verwalten sowie Python-Pakete bauen und veröffentlichen. Für den Einstieg sind diese Funktionen nicht erforderlich. Die bisher gezeigten Kommandos decken den Großteil der alltäglichen Script-Projekte ab.

08 — Einordnung

Alternativen

uv ist nicht der einzige Weg zu ordentlich verwalteten Python-Projekten. Die Kombination aus venv, pip und requirements.txt funktioniert weiterhin und benötigt kein zusätzliches Werkzeug. Für kleine, rein lokale Projekte kann das vollkommen ausreichen.

pip-tools ergänzt pip um besser reproduzierbare Abhängigkeitsdateien. Poetry und PDM bieten wie uv eine umfassende Projektverwaltung. Hatch richtet sich besonders an die Entwicklung und Veröffentlichung von Python-Paketen. Pixi ist interessant, wenn neben Python-Paketen auch native Bibliotheken aus dem Conda-Umfeld verwaltet werden müssen.

Wenn ein bestehendes Projekt mit einem dieser Werkzeuge zuverlässig funktioniert, gibt es keinen zwingenden Grund für einen Wechsel. Für neue Script-Projekte überzeugt uv aber durch die einfache Bedienung, die hohe Geschwindigkeit und den großen Funktionsumfang.

09 — Fazit

Weniger Handarbeit bei Python-Projekten

Mit uv benötigen Sie nur wenige Kommandos, um ein Python-Projekt einzurichten, Module zu installieren und den Code in der richtigen Umgebung auszuführen. Gleichzeitig entstehen mit pyproject.toml und uv.lock klare Vorgaben für die Weitergabe des Projekts.

Besonders angenehm ist, dass Sie das Virtual Environment normalerweise weder selbst erzeugen noch aktivieren müssen. uv run erledigt die notwendigen Schritte automatisch. uv tool install und uvx lösen außerdem das verwandte Problem der global installierten Python-Programme.

Kurz und gut: Wenn Sie ein neues Python-Projekt beginnen, lohnt es sich, uv auszuprobieren. Der Zeitaufwand für die Einarbeitung ist gering. Dafür ersparen Sie sich später viele Fragen zur Python-Version, zum richtigen pip-Kommando und zum Zustand des Virtual Environments.