Was lerne ich in diesem Kurs?

In diesem Tutorial lernst du, wie man Uv installiert, ein neues Projekt erstellt, ein virtuelles Environment anlegt und Pakete verwaltet.

Tutorial: Uv Package Management

Themen

• Installation auf Windows (mit pip und brew)
• Abhängigkeit von Python-Versionen und Python-Management
• Erstellung eines Beispielprojekts mit FastAPI, SQLAlchemy, und Alembic mit uv

Installation von Uv auf Windows

Öffne die Eingabeaufforderung und führe den folgenden Befehl aus, um uv zu installieren:

pip install uv

Installation mit MacOSX

Falls du Homebrew nutzt:

Installiere uv einfach mit:

brew install uv

Installation von Uv auf Linux

Öffne ein Terminal und führe den folgenden Befehl aus, um uv zu installieren:

pip install uv

Python-Versionen verwalten

Da uv von bestimmten Python-Versionen abhängig ist, kannst du mit dem folgenden Befehl alle installierten Python-Versionen auflisten:

uv python list

Dieser Befehl zeigt alle Python-Versionen an, die uv verwenden kann.

Projektinitialisierung mit uv

Nach der Installation von uv, lass uns ein Beispielprojekt erstellen. Wir nutzen FastAPI, SQLAlchemy, und Alembic, um eine einfache Webanwendung zu erstellen.

Projekt erstellen:

uv init --python 3.12 my_project

Dieser Befehl initialisiert ein neues Projekt mit Python 3.12. Es erstellt eine grundlegende Projektstruktur mit folgenden Dateien:

• pyproject.toml: Beschreibt die Metadaten des Projekts und enthält Informationen wie Abhängigkeiten und die Python-Version.
• .python-version: Enthält die verwendete Python-Version.
• README.md: Ein Platzhalter für Projektdokumentation.
• .gitignore: Listet Dateien auf, die nicht in Git eingecheckt werden sollen (z.B. die virtuelle Umgebung).

Was ist pyproject.toml?

pyproject.toml ist die zentrale Konfigurationsdatei für moderne Python-Projekte. Sie enthält Angaben zu:

• requires_python: Gibt die Python-Version an, die für das Projekt erforderlich ist.
• dependencies: Eine Liste aller Bibliotheken und deren Versionen, die für das Projekt benötigt werden.

Beispiel pyproject.toml:

[project]
name = "my_project"
requires_python = ">=3.12"

[dependencies]
fastapi = ">=0.115.2"
sqlalchemy = ">=2.0.36"
alembic = ">=1.13.3"

Hinzufügen von Abhängigkeiten

Nach der Projektinitialisierung fügen wir unsere Abhängigkeiten hinzu:

uv add fastapi sqlalchemy alembic

Dies aktualisiert die pyproject.toml und fügt die Pakete hinzu. Nun sieht die Datei so aus:

[dependencies]
fastapi = ">=0.115.2"
sqlalchemy = ">=2.0.36"
alembic = ">=1.13.3"

Dabei wird auch eine virtuelle Umgebung (in .venv) erstellt. Diese Umgebung enthält alle installierten Abhängigkeiten und isoliert das Projekt von globalen Python-Installationen.

Was ist uv.lock?

uv.lock ist eine Lockdatei, die die exakten Versionen der installierten Pakete speichert, um sicherzustellen, dass bei jeder Installation dieselben Abhängigkeiten verwendet werden.

uv run - Programme direkt starten

Mit dem Befehl uv run kann man Programme in der virtuellen Umgebung gezielt direkt starten. Du musst die virtuelle Umgebung nicht manuell aktivieren – uv erledigt das für dich.

Erstellen einer einfachen FastAPI-App

Erstelle eine Datei code.py:

from fastapi import FastAPI

app = FastAPI()

@app.get("/", status_code=200)
def index():
    return {"message": "Hello World"}

Dieser einfache Code erstellt eine FastAPI-Anwendung mit einer einzigen Route, die eine "Hello World"-Nachricht zurückgibt.

Webserver hinzufügen

FastAPI benötigt einen Webserver wie Uvicorn, um Anfragen zu verarbeiten. Füge Uvicorn hinzu:

uv add uvicorn

Projekt starten

Starte das Projekt mit:

uv run uvicorn code:app --reload

Erklärung:

• uvicorn code:app: Startet den Uvicorn-Server und nutzt die app-Instanz in der Datei code.py.
• --reload: Aktiviert den Hot-Reload, sodass Änderungen am Code automatisch erkannt und der Server neu gestartet wird.

Uv Sync

The uv sync command synchronizes your project’s dependencies according to the uv.lock file. This command ensures that all packages are installed in the exact versions specified in the lock file.

Beispiel:

Löschen wir die virtuelle Umgebung .venv:

rm -rf .venv

Führen wir den folgenden Befehl aus, um die Dependencies wiederherzustellen:

uv sync

Nach Ausführung dieses Befehls werden alle Abhängigkeiten neu installiert, und die exakten Versionen aus uv.lock werden übernommen. Dies stellt sicher, dass dein Projekt dieselben Abhängigkeiten nutzt, unabhängig von der Maschine, auf der es läuft.

Dev-Dependencies

Uv erlaubt es, Entwicklungsabhängigkeiten getrennt von Produktionsabhängigkeiten zu verwalten. Diese "dev-dependencies" sind nützlich für Tools wie Linter und Typprüfer, die du während der Entwicklung benötigst, aber nicht in der Produktionsumgebung.

Beispiel:

Fügen wir mypy und ruff als Dev-Dependencies hinzu:

uv add ruff mypy --dev

Das fügt die Tools zur pyproject.toml als Entwicklungsabhängigkeiten hinzu:

[tool.uv]
dev-dependencies = [
    "mypy>=1.12.1",
    "ruff>=0.7.0",
]

Diese Abhängigkeiten werden nur installiert, wenn du im Entwicklungsmodus arbeitest, und nicht in der Produktionsumgebung.

Uv Remove

Mit dem Befehl uv remove kannst du eine Abhängigkeit aus dem Projekt entfernen, und zwar entweder aus den regulären oder den Entwicklungsabhängigkeiten.

Beispiel:

Um FastAPI zu entfernen:

uv remove fastapi

Um eine Entwicklungsabhängigkeit wie mypy zu entfernen:

uv remove mypy --dev

Nach der Ausführung dieser Befehle wird die Abhängigkeit sowohl aus der pyproject.toml als auch aus der Lockdatei entfernt.

Uv Tree

Der uv tree Befehl zeigt die Abhängigkeiten deines Projekts in einer baumartigen Struktur, was eine einfache Übersicht über alle Pakete und deren Verschachtelung bietet.

Beispiel:

uv tree

Dies gibt eine Ausgabe wie diese:

Resolved 20 packages in 0.72ms
project v0.1.0
├── alembic v1.13.3
│   ├── mako v1.3.5
│   │   └── markupsafe v3.0.2
├── fastapi v0.115.2
│   ├── pydantic v2.9.2
│   └── starlette v0.40.0
└── uvicorn v0.32.0

Diese Baumstruktur zeigt dir nicht nur deine direkten Abhängigkeiten, sondern auch deren Unterabhängigkeiten.

uv tree -d 1:

Dieser Befehl zeigt nur die erste Ebene der Abhängigkeiten, also die direkten Abhängigkeiten:

uv tree -d 1

With-Option für ad-hoc Dependencies

Du kannst Abhängigkeiten auch temporär, ohne sie zur pyproject.toml hinzuzufügen, installieren. Dies ist nützlich, wenn du eine Abhängigkeit nur für ein einzelnes Skript benötigst.

Beispiel:

Erstelle die Datei api.py:

import requests

response = requests.get("http://localhost:8000/")
print(response.json())

Starte das Skript mit einer ad-hoc Dependency:

uv run --with requests api.py

Dabei wird requests nur temporär installiert und nach der Ausführung wieder entfernt.

Uv Tool

Ruff bietet die Möglichkeit, ein Tool auszuführen, ohne es extra zu installieren. Das ist zum Beispiel sinnvoll im Umgang mit Lintern wie ruff. Dabei wird das Tool temporär installiert, wird aber nicht in die pyproject.toml - Datei als Dependency eingetragen.

uv run tool ruff

oder in der Kurzform

uvx ruff

oder mit einer bestimmen Versionsnummer

uvx ruff@0.3.0 check

Um beispielsweise eine Datei mit ruff zu formatieren, wird das format-Subkommando samt Argument benötigt. Man könnte schreiben:

uvx ruff format main.py

Inline Script Metadata (PEP 723)

Uv unterstützt Inline-Metadaten in Python-Skripten nach dem PEP 723-Standard. Du kannst in deinem Python-Skript die benötigten Abhängigkeiten direkt angeben, und Uv wird diese automatisch installieren.

Beispiel:

Füge in api.py folgende Inline-Metadaten hinzu:

   # /// script
   # requires-python = ">=3.11"
   # dependencies = [
   #   "requests<3",
   #   "rich",
   # ]
   # ///

Starte das Skript mit:

uv run api.py

Uv liest die Abhängigkeiten aus dem Skript und installiert sie automatisch, bevor es das Skript ausführt.

Generierung von Script-Metadaten:

Du kannst Uv auch verwenden, um Inline-Skript-Metadaten automatisch zu generieren:

uv add --script api.py 'requests<3' 'mypy'

Dadurch wird folgendes Inline-Kommentar hinzugefügt:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "mypy",
#     "requests<3",
# ]
# ///

Pip API Integration

Uv bietet eine Integration mit der pip API, was es ermöglicht, pip-Kommandos direkt mit uv auszuführen.

• uv pip freeze: Zeigt alle installierten Abhängigkeiten in der virtuellen Umgebung an:

uv pip freeze

• uv pip install: Installiere ein Paket direkt mit pip in der uv-verwalteten Umgebung:

uv pip install <package_name>