Was macht uv — Schneller Python-Paket- und Projektmanager?
Überblick
uv ist ein einzelnes Binärprogramm von Astral, das den gesamten Python-Workflow abdeckt: Projekte mit einer plattformübergreifenden Lockdatei (uv.lock), Einzeldatei-Skripte mit Inline-Abhängigkeiten, Kommandozeilenwerkzeuge (uvx), Python-Interpreter-Installationen und eine Drop-in-uv pip-Schnittstelle. Es lädt Python bei Bedarf selbst herunter, sodass ein Rechner nichts außer uv benötigt.
Anleitung
Installation
# Paketmanager
pipx install uv
brew install uv
winget install --id=astral-sh.uv -e
Astral veröffentlicht auch einen eigenständigen Installer für Rechner ohne Paketmanager; die Installationsseite unter https://docs.astral.sh/uv/getting-started/installation/ enthält den aktuellen Befehl und Prüfsummen.
uv --version
uv self update # nur für eigenständigen Installer; andernfalls mit dem Paketmanager aktualisieren
Um eine bestimmte Version festzulegen, setzen Sie die Version in die Installer-URL: https://astral.sh/uv/0.12.21/install.sh.
Ein Projekt erstellen
uv init dispatch-api # verpackte App: src/dispatch_api/, uv_build Backend, Konsolenskript
uv init --no-package cron-jobs # flaches Layout mit main.py und keinem Build-System
uv init --lib geo-utils # Bibliothek mit py.typed-Marker
uv init --bare --python 3.12 # nur pyproject.toml, im aktuellen Verzeichnis
uv init schreibt auch .python-version, README.md, .gitignore und initialisiert Git. --bare schreibt nur pyproject.toml, was es zur richtigen Wahl innerhalb eines bestehenden Repositorys macht.
Abhängigkeiten verwalten
uv add 'httpx>=0.27' 'pydantic>=2.7,<3' # Laufzeitabhängigkeiten
uv add --dev pytest ruff # Dev-Gruppe, nicht in Produktion ausgeliefert
uv add --group docs mkdocs # eine beliebige benannte Abhängigkeitsgruppe
uv add --optional postgres 'psycopg[binary]' # extra: pip install dispatch-api[postgres]
uv add -r requirements.txt # eine vorhandene requirements-Datei importieren
uv remove httpx
uv lock --upgrade-package pydantic # ein Paket innerhalb seiner Beschränkungen aktualisieren
uv lock --upgrade # alles aktualisieren
uv tree --outdated --depth 1 # was hat eine neuere Version
Der erste uv add erstellt .venv/ und uv.lock. Jede Änderung aktualisiert pyproject.toml, die Lockdatei und die Umgebung gemeinsam.
Ausführen und Synchronisieren
uv run pytest # sperrt und synchronisiert bei Bedarf, führt dann innerhalb von .venv aus
uv run python -m dispatch_api
uv run --with rich python -c "import rich" # ein zusätzliches Paket nur für diesen Befehl
uv sync # alles installieren, inklusive Dev-Gruppe
uv sync --locked # CI: fehlschlagen, wenn uv.lock nicht mit pyproject.toml übereinstimmt
uv sync --frozen --no-dev # Produktion: uv.lock unverändert verwenden, Dev-Gruppe überspringen
uv sync --extra postgres
uv lock --check # mit Exit-Code ungleich Null beenden, wenn die Lockdatei veraltet ist
Keine Aktivierung erforderlich; uv run findet die Projektumgebung automatisch.
Skripte mit Inline-Abhängigkeiten
uv init --script fetch-rates.py --python 3.12
uv add --script fetch-rates.py 'httpx<1' rich
uv run fetch-rates.py
uv lock --script fetch-rates.py # schreibt fetch-rates.py.lock für reproduzierbare Ausführungen
uv add --script pflegt einen Metadatenblock am Anfang der Datei:
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "httpx<1",
# "rich>=15.0.0",
# ]
# ///
Fügen Sie #!/usr/bin/env -S uv run --script als erste Zeile hinzu und führen Sie chmod +x für die Datei aus, um sie direkt auszuführen.
Werkzeuge
uvx ruff check . # ausführen ohne Installation; uvx = uv tool run
uvx [email protected] check . # genaue Version
uvx --from 'markitdown[pdf]' markitdown q3-board-report.pdf # Befehlsname unterscheidet sich vom Paket
uv tool install ruff # permanente, isolierte Installation auf dem PATH
uv tool upgrade --all
uv tool list
uv tool uninstall ruff
Installierte Werkzeuge landen im Verzeichnis, das uv tool dir --bin ausgibt; uv warnt, wenn dieses Verzeichnis nicht im PATH ist.
Python-Versionen
uv python install 3.12 3.13
uv python list --only-installed
uv python pin 3.12 # schreibt .python-version
uv run --python 3.13 pytest # einmalige Ausführung mit einem anderen Interpreter
uv python upgrade 3.12 # neuestes Patch-Release von 3.12
uv venv --python 3.12 # einfache virtuelle Umgebung unter .venv
Anfragen akzeptieren 3.12, 3.12.3, >=3.11,<3.13, [email protected] und 3.13t (frei threaded). uv lädt einen fehlenden Interpreter automatisch herunter; übergeben Sie --no-python-downloads, um das zu verbieten.
pip-kompatible Schnittstelle
uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt --universal
uv pip sync requirements.txt # entfernt alles, was nicht aufgeführt ist
uv pip install --python .venv/bin/python 'rich>=13'
CI und Docker
name: ci
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
version: "0.12.21"
enable-cache: true
- run: uv python install
- run: uv sync --locked --all-extras --dev
- run: uv run pytest
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:0.12.21 /uv /uvx /bin/
WORKDIR /app
ENV UV_NO_DEV=1 UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
# Abhängigkeiten zuerst, damit dieser Layer wiederverwendet wird, bis uv.lock sich ändert
RUN --mount=type=cache,target=/root/.cache/uv \
--mount=type=bind,source=uv.lock,target=uv.lock \
--mount=type=bind,source=pyproject.toml,target=pyproject.toml \
uv sync --locked --no-install-project
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv uv sync --locked
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "dispatch_api"]
Fügen Sie .venv zur .dockerignore hinzu; eine Host-Umgebung funktioniert nicht innerhalb des Images.
Beispiele
Beispiel 1: Einen requirements.txt-Dienst zu einem gelockten uv-Projekt migrieren
Anfrage: "Unser dispatch-api-Repository hat requirements.txt und requirements-dev.txt. Migriere es zu uv mit einer Lockdatei und lasse die Tests laufen."
cd dispatch-api
uv init --bare --python 3.12
uv python pin 3.12
uv add -r requirements.txt
sed '/^-r /d' requirements-dev.txt | uv add --dev -r -
uv run python -m pytest -q
uv run ruff check .
Ergebnis: pyproject.toml listet die fünf Laufzeitpakete und eine dev-Gruppe auf, uv.lock fixiert 30 Pakete, und die Prüfungen bestehen. Gekürzte Ausgabe:
Initialized project `dispatch-api`
Pinned `.python-version` to `3.12`
+ uvicorn==0.34.0
+ pytest==8.3.4
+ ruff==0.8.6
1 passed, 1 warning in 0.12s
All checks passed!
Beispiel 2: Ein eigenständiges Skript
Anfrage: "Schreibe ein Skript zur Festplattennutzung, das ich auf jeden Server kopieren und ohne Einrichtung einer Umgebung ausführen kann."
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["rich>=13"]
# ///
import shutil
from rich.console import Console
from rich.table import Table
usage = shutil.disk_usage("/")
table = Table(title="Festplattennutzung")
table.add_column("Gesamt GB")
table.add_column("Frei GB")
table.add_row(f"{usage.total / 1e9:.0f}", f"{usage.free / 1e9:.0f}")
Console().print(table)
chmod +x disk-report.py
./disk-report.py
Ergebnis: uv erstellt beim ersten Durchlauf eine gecachte Umgebung mit rich und gibt die Tabelle aus; spätere Durchläufe starten sofort.
Festplattennutzung
┏━━━━━━━━━━┳━━━━━━━━━┓
┃ Gesamt GB ┃ Frei GB ┃
┡━━━━━━━━━━╇━━━━━━━━━┩
│ 3936 │ 2211 │
└──────────┴─────────┘
Richtlinien
uv.lockund.python-versioncommitten. Bearbeiten Sieuv.lockniemals manuell; ändern Siepyproject.tomloder verwenden Sieuv add,uv removeunduv lock.--lockedoder--frozen:--lockedüberprüft die Lockdatei und schlägt fehl, wenn sie veraltet ist, was sich für CI eignet.--frozenüberspringt die Prüfung und installiert genau das, was die Datei angibt.uv syncist exakt,uv runnicht.uv syncentfernt Pakete, die nicht in der Lockdatei sind, einschließlich aller mituv pip installhinzugefügten.uv runfügt nur hinzu, was fehlt.uv pipwählt sein Ziel durch Erkennung: die aktiveVIRTUAL_ENV, dann.venvim aktuellen Verzeichnis oder im nächstgelegenen Elternverzeichnis. Wenn Sie es aus dem falschen Ordner ausführen, installiert es in die Umgebung eines anderen. Übergeben Sie in Skripten--pythonmit dem Umgebungspfad.- Flache Projekte und pytest: Bei
--bareoder--no-packagewird das Projekt selbst nicht installiert, daher kannuv run pytestmitModuleNotFoundErrorfehlschlagen. Verwenden Sieuv run python -m pytest, oder setzen Siepythonpath = ["."]unter[tool.pytest.ini_options]. uv initstandardmäßig auf ein verpacktessrc/-Layout. Übergeben Sie--no-packagefür ein skriptartiges Projekt mitmain.py.- Experimentelle Befehle:
uv format,uv checkunduv auditgeben eine Warnung aus, dass sie sich ändern könnten. Bauen Sie noch keine Pipelines darauf auf. - Private Indizes: Deklarieren Sie diese unter
[[tool.uv.index]]und übergeben Sie Anmeldeinformationen über Umgebungsvariablen, die nach dem Index benannt sind: für einen Index namensinternal,UV_INDEX_INTERNAL_USERNAMEundUV_INDEX_INTERNAL_PASSWORD. Committen Sie diese niemals. Die Standard-first-index-Strategie schützt vor Dependency-Confusion; vermeiden Sieunsafe-best-match. - Lieferkette:
uv run,uvxund Skripte mit Inline-Metadaten laden Pakete herunter und führen sie aus. Überprüfen Sie die Abhängigkeitsliste jedes Skripts aus einer nicht vertrauenswürdigen Quelle, bevor Sie es ausführen. uv self updatefunktioniert nur für Installationen, die mit dem eigenständigen Installer durchgeführt wurden.- CI-Cache: Führen Sie
uv cache prune --ciaus, bevor Sie den Cache speichern, um ihn klein zu halten. - Wann NICHT verwendet werden sollte: uv installiert von Python-Paketindizes, Git und lokalen Pfaden. Es installiert keine Conda-Pakete oder Systembibliotheken, behalten Sie Conda daher für Stacks, die davon abhängen.