So richtest du ein schnelles, reproduzierbares Python-Projekt mit uv ein

Wenn du einen KI-Coding-Agenten wie Claude Code oder Codex auf ein Python-Projekt ansetzt, hat die Hälfte der Reibung nichts mit dem Modell zu tun. Sie kommt von der Umgebung: fehlende Pakete, die falsche Python-Version, ein virtualenv, das der Agent zu aktivieren vergessen hat, oder eine Kollegin, bei der es „auf meinem Rechner funktioniert“. Die Lösung ist ein Projekt, das standardmäßig reproduzierbar ist, und der schnellste Weg dorthin ist heute uv, die in Rust geschriebene Python-Toolchain von Astral.

uv ersetzt pip, venv, pip-tools und pyenv durch einen einzigen schnellen Befehl und schreibt eine Lockfile, sodass überall exakt derselbe Abhängigkeitsbaum installiert wird. Diese Anleitung bringt dich in wenigen Minuten von null zu einem gelockten, lauffähigen Projekt.

Warum die Umgebung für einen Agenten wichtig ist

Ein KI-Agent führt Befehle in deiner Shell aus und liest die Fehler, die zurückkommen. Wenn dein Projekt keine deklarierten Abhängigkeiten und keine festgelegte Python-Version hat, muss der Agent raten – und ein falscher Tipp schickt ihn auf eine Odyssee, Pakete global zu installieren oder den falschen Interpreter zu bearbeiten. Ein Projekt mit einer pyproject.toml und einer uv.lock gibt dem Agenten eine einzige verlässliche Quelle: Er kann uv sync ausführen, die richtigen Pakete bekommen und weitermachen. Deine Review-Zeit verbringst du dann mit Logik, nicht mit Umgebungsarchäologie.

uv installieren

Unter macOS oder Linux:

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

Unter Windows (PowerShell):

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

uv ist eine einzelne, in sich geschlossene Binary, sodass es sonst nichts zu konfigurieren gibt.

Ein Projekt mit einem einzigen Befehl starten

uv init weather-cli
cd weather-cli

Das erstellt ein funktionsfähiges Projektgerüst: eine pyproject.toml für Metadaten und Abhängigkeiten, eine .python-version-Datei, eine Start-main.py, eine README.md und eine .gitignore. Du erstellst oder aktivierst kein virtualenv von Hand – uv verwaltet ein .venv für dich, sobald du es brauchst.

Abhängigkeiten hinzufügen (und warum die Lockfile zählt)

uv add requests

Das erledigt drei Dinge auf einmal: Es trägt requests in der pyproject.toml ein, löst den vollständigen Abhängigkeitsbaum auf und schreibt uv.lock mit exakten, plattformübergreifend festgelegten Versionen. Du kannst auch direkt beim Hinzufügen eine Version festlegen:

uv add 'requests==2.31.0'

Committe uv.lock in Git. Das ist der Unterschied zwischen „installiere das neueste requests“ (was im Lauf der Zeit driftet) und „installiere den exakten Baum, den wir getestet haben“. Wenn dein Agent – oder deine CI oder ein neues Teammitglied – uv sync ausführt, bekommen sie eine Byte für Byte identische Umgebung.

Code ausführen, ohne etwas zu aktivieren

uv run main.py

uv run stellt sicher, dass die Umgebung synchron ist, und führt dann darin aus – kein source .venv/bin/activate-Tanz. Das ist besonders für Agenten wichtig: Jeder Tool-Aufruf ist oft eine frische Shell, sodass „aktivieren, dann ausführen“ häufig scheitert, während ein einziges uv run immer funktioniert. Du kannst jeden beliebigen Befehl umschließen:

uv run -- pytest -q
uv run -- flask run -p 3000

Eine Python-Version festlegen, damit Agent und CI übereinstimmen

uv python pin 3.12

Das schreibt die Version in .python-version, und uv lädt und verwendet diesen Interpreter automatisch – kein System-Python erforderlich. Jetzt ist die Version, gegen die du entwickelst, dieselbe, die dein Agent, deine Teammitglieder und deine CI alle verwenden.

Ein kurzes durchgespieltes Beispiel

Angenommen, du bittest einen Agenten, „einen Befehl hinzuzufügen, der das heutige Wetter abruft“. Mit uv an Ort und Stelle ist die gesamte Schleife sauber:

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# der Agent bearbeitet main.py, um eine API aufzurufen ...
uv run main.py

Der Agent muss nie darüber nachdenken, welcher Interpreter aktiv ist oder ob requests installiert ist – diese Fakten sind in Dateien deklariert, die er lesen kann. Führt er eine neue Abhängigkeit ein, ruft er uv add auf, und die Lockfile aktualisiert sich. Geht in der CI etwas schief, reproduziert uv sync die exakte Umgebung lokal, sodass du sie debuggen kannst.

Wohin uv sich entwickelt

uv und seine Geschwister-Tools ruff (Linter/Formatter) und ty (Type-Checker) sind weit verbreitet – allein uv verzeichnet weit über 100 Millionen Downloads pro Monat. Im März 2026 hat OpenAI zugestimmt, Astral zu übernehmen, das Unternehmen dahinter, um die Toolchain in seine Codex-Plattform einzugliedern, und sich dabei verpflichtet, die MIT-lizenzierten Tools Open Source zu halten (OpenAI, Simon Willison). Vorerst bleibt die praktische Erkenntnis unverändert: uv ist der schnellste Weg zu einem Python-Projekt, auf dem dein KI-Agent bauen kann, ohne zu raten.

Kurzreferenz

Aufgabe	Befehl
Ein Projekt erstellen	uv init <name>
Eine Abhängigkeit hinzufügen	uv add <package>
Python festlegen	uv python pin 3.12
Code ausführen	uv run <file or command>
Die Umgebung reproduzieren	uv sync
Die Lockfile aktualisieren	uv lock --upgrade-package <pkg>