Der Track für KI-Engineers und Entwicklungsumgebungen mit uv

Das Problem, das wir lösen

Ein neuer KI-Engineer stößt zu einem Team. Die Aufgabe am ersten Tag ist einfach: das Projekt auf dem eigenen Laptop zum Laufen bringen. Die README sagt: „run python main.py“. Die Person führt es aus und bekommt ModuleNotFoundError: No module named 'httpx'. Auf dem Rechner der Person, die das Projekt geschrieben hat, funktioniert derselbe Befehl einwandfrei.

Beim Nachforschen stellt sich heraus: Seit zwei Jahren sammeln sich auf dem Rechner, auf dem das Projekt entstanden ist, im selben Python alle Pakete an, die jemals irgendein Projekt dort gebraucht hat. Welche Pakete dieses Projekt braucht, steht nirgends geschrieben — nur „auf meinem Rechner funktioniert es“. Das neue Teammitglied verbringt einen halben Tag damit, Pakete einzeln zu finden und zu installieren, und am Ende ist eines davon in einer anderen Version, sodass auch die Ergebnisse abweichen.

Professionelle Teams haben dafür eine Antwort: Jedes Projekt bekommt seine eigene isolierte Umgebung, und was diese Umgebung enthält, steht in einer Datei — so kann jeder mit einem einzigen Befehl genau dieselbe Umgebung aufbauen. Genau das bauen wir in diesem Kapitel — mit uv — und genau das verwenden wir für den Rest des Kurses.

Am Ende dieses Kapitels kannst du

• Python sowohl mit dem normalen Installer als auch mit uv python install installieren und erklären, worin sich die beiden unterscheiden
• Erklären, was pip ist und warum dieser Kurs stattdessen uv verwendet
• Mit uv init, uv add, uv run und uv venv eine isolierte Projektumgebung erstellen und ausführen
• An einem Beispiel zeigen, warum Projekte nicht mit dem System-Python laufen sollten
• In VS Code oder PyCharm den eigenen Interpreter des Projekts auswählen

Was du vorher brauchst: in einem Terminal den Ordner wechseln (cd) und einen Befehl ausführen. Dies ist das erste Kapitel des Kurses, also brauchst du nichts weiter.

So funktioniert dieser Track

Dieser Kurs ist ein Karriere-Track. Jedes Kapitel ist wie eine Unterrichtsstunde, und jedes endet mit einer Aufgabe, die du auf deinem eigenen Rechner ausführst. Die ersten Kapitel legen das Fundament professioneller Arbeit — Umgebungen, Git, Projektstruktur, Konfiguration. Danach folgen sauberes Python, Testen, APIs, Datenbanken, RAG, Sicherheit und Deployment.

Eines solltest du gleich am Anfang wissen: In einer Firma wird der Code eines KI-Engineers nicht akzeptiert, nur weil er „läuft“. Ob ihn jemand anderes auf dem eigenen Rechner ausführen kann, ob jemand ihn reviewen kann, ob ihn in sechs Monaten noch jemand versteht — das gehört auch zur Arbeit. Deshalb ist jede praktische Aufgabe in diesem Kurs so aufgebaut, als würde sie in das Repository eines echten Teams wandern. Und der erste Schritt dieser Gewohnheit ist die Umgebung.

Python installieren: zwei Wege

Weg eins — der normale Installer. Lade den Installer für 3.12 von python.org herunter und starte ihn. Unter Windows hakst du auf dem allerersten Bildschirm Add python.exe to PATH an; ohne das erkennt das Terminal den Befehl python nicht. Unter macOS reicht es, das .pkg von python.org auszuführen. Unter Linux ist python3 meist schon vorhanden — dazu gibt es unten eine Warnung.

Zum Prüfen:

python --version
Python 3.12.0

Unter macOS und Linux heißt der Befehl oft python3 --version.

Weg zwei — mit uv. uv ist ein einziges Werkzeug, das Python-Versionen, Projektumgebungen und Pakete übernimmt. Installiere zuerst uv. Unter macOS und Linux:

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

In Windows PowerShell:

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

Öffne danach ein neues Terminal:

uv --version
uv 0.9.1 (9887ef5bd 2025-10-09)

Deine Versionsnummer kann abweichen. Jetzt Python:

uv python install 3.12
Installed Python 3.12.11 in 27.42s
 + cpython-3.12.11-windows-x86_64-none (python3.12.exe)

Die Zeit und der Plattformname am Ende sehen bei dir anders aus. Beachte: Das Python, das uv installiert hat, liegt in einem eigenen Ordner — es fasst das Haupt-Python des Rechners nicht an, und es ändert auch den PATH nicht.

Beide Wege können nebeneinander bestehen, und für diesen Kurs funktionieren beide. Der Unterschied: Der normale Installer gibt dir ein Python für den ganzen Rechner; uv python install gibt dir Pythons, die sich Projekte je nach Bedarf aussuchen. Das eine Projekt braucht 3.12, ein anderes 3.13 — keines stört das andere.

Was pip ist und warum wir uv verwenden

Die externen Pakete von Python — httpx, pydantic, fastapi — liegen in einem Repository namens PyPI. Das klassische Werkzeug, um sie zu holen, ist pip, das mit Python mitkommt. Fast jedes Tutorial im Internet schreibt pip install ....

pip funktioniert gut, erledigt aber nur eine Aufgabe: Pakete installieren. Und es installiert sie in das Python, mit dem es gerade gestartet wurde. Für ein professionelles Projekt braucht alles andere ein eigenes Werkzeug:

• die richtige Python-Version besorgen — ein eigenes Werkzeug
• eine isolierte Umgebung erstellen und aktivieren — python -m venv, dann activate von Hand
• festhalten, was das Projekt braucht — von Hand, in einer Datei, oft vergessen
• genau festhalten, welche Version jedes Pakets verwendet wurde (ein Lockfile) — noch ein Werkzeug

uv erledigt alle vier in einem einzigen Werkzeug und ist dabei deutlich schneller. Am wichtigsten: Wenn du mit uv add etwas hinzufügst, wird es automatisch in die Projektdatei eingetragen. „Ich habe es installiert, aber vergessen aufzuschreiben“ — die Ursache für das Problem des neuen Teammitglieds oben — kann so nicht passieren.

Überall im Kurs, wo Pakete oder Umgebungen vorkommen, nimmst du also uv. Wenn du irgendwo anders pip install siehst, ist das uv-Gegenstück fast immer uv add.

Warum das System-Python kein Ort für Projekte ist

Das „System-Python“ ist das Python, das direkt auf dem Rechner installiert ist — das, das läuft, wenn du im Terminal python eingibst, ohne eine Umgebung zu aktivieren. Die Pakete eines Projekts dort hineinzuinstallieren verursacht drei Probleme:

1. Alle teilen sich einen Raum. Ein Projekt braucht pydantic 1, ein anderes 2. Das System-Python kann nur eine Version halten, also bricht die Reparatur des einen Projekts das andere.
2. Abhängigkeiten werden unsichtbar. Das Paket war schon für ein altes Projekt installiert, also läuft das neue Projekt — doch nirgends im Projekt steht, dass es dieses Paket braucht. Auf deinem Rechner erscheint kein Fehler; der Fehler taucht auf dem Rechner eines anderen Teammitglieds oder auf dem Server auf.
3. Das Betriebssystem benutzt es. Unter macOS und Linux laufen manche Systemwerkzeuge mit diesem Python. Wenn man seine Pakete ändert, kann man sie kaputtmachen — deshalb blockieren neuere Linux-Versionen die direkte Installation ins System-Python.

Das zweite Problem ist das gefährlichste, weil es still passiert. Das System-Python auf dem Rechner, auf dem dieses Kapitel geschrieben wurde, hat noch httpx, pydantic und rich aus alter Arbeit. Daher „läuft“ dort jedes Skript — und genau deshalb lässt sich daran nicht erkennen, was ein Skript wirklich braucht.

Der Irrglaube lautet: „Es läuft auf meinem Rechner, also passt es.“ Ein Skript, das auf dem System-Python läuft, beweist nur, dass das Paket irgendwann einmal auf deinem Rechner installiert war. Was das Projekt selbst braucht, zeigt sich erst, wenn alles aus der eigenen Datei des Projekts in eine leere Umgebung installiert ist und das Skript dort läuft.

Ein erstes Projekt mit uv

Im Arbeitsordner gibst du ein:

uv init hello-ai --python 3.12
Initialized project `hello-ai` at `D:\ai-lab\hello-ai`

(Der Pfad am Ende zeigt deinen eigenen Ordner; die Ausgaben in diesem Kapitel kürzen die Pfade.) uv init legt einen neuen Ordner an, und darin:

hello-ai/
├── .git/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

Am wichtigsten davon ist pyproject.toml — der Ausweis des Projekts:

[project]
name = "hello-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

dependencies = [] — das Projekt braucht noch kein externes Paket. .python-version enthält nur 3.12: das Python, mit dem dieses Projekt läuft. Und uv init hat für dich ein Git-Repository und eine .gitignore angelegt — die kommen im nächsten Kapitel zum Einsatz.

Jetzt führe es aus:

cd hello-ai
uv run main.py
Using CPython 3.12.11
Creating virtual environment at: .venv
Hello from hello-ai!

Beim ersten Mal hat uv run von selbst einen Ordner .venv angelegt — das ist die isolierte Umgebung des Projekts — und dann main.py mit dem Python dieser Umgebung ausgeführt. Aktivieren musstest du nichts.

uv add: ein Paket hinzufügen und festhalten

Fast jedes Projekt, an dem ein KI-Engineer arbeitet, ruft irgendeine API auf. Deshalb ist das erste Paket der HTTP-Client httpx, dazu python-dotenv, um .env-Dateien zu lesen:

uv add httpx python-dotenv
Resolved 9 packages in 119ms
Installed 8 packages in 92ms
 + anyio==4.15.1
 + certifi==2026.7.22
 + h11==0.16.0
 + httpcore==1.0.9
 + httpx==0.28.1
 + idna==3.20
 + python-dotenv==1.2.3
 + typing-extensions==4.16.0

Du hast zwei Pakete angefordert und acht bekommen — die übrigen sind die eigenen Abhängigkeiten von httpx, die uv selbst herausgefunden hat. Die Versionsnummern können bei dir neuer sein.

Schau dir jetzt pyproject.toml an:

[project]
name = "hello-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "httpx>=0.28.1",
    "python-dotenv>=1.2.3",
]

Ein Befehl hat drei Dinge getan: Die Pakete wurden in .venv installiert, pyproject.toml hält jetzt fest, dass das Projekt sie braucht, und es ist eine neue Datei uv.lock entstanden, die die genaue Version aller acht Pakete festschreibt. Lockfiles behandeln wir später im Kurs ausführlich; für jetzt reicht es zu wissen, dass ein Teammitglied, das das Repository klont und uv sync ausführt, genau diese acht Versionen bekommt.

Um etwas wieder zu entfernen, nimmst du uv remove:

uv remove python-dotenv
Resolved 8 packages in 21ms
Uninstalled 1 package in 11ms
 - python-dotenv==1.2.3

Auch das wirkt an beiden Stellen: Es entfernt das Paket aus .venv und löscht es aus pyproject.toml.

uv venv und das Aktivieren von Hand

uv run erstellt und verwendet die Umgebung für dich, deshalb reicht es in diesem Kurs fast immer. Manchmal brauchst du aber einfach eine leere Umgebung — zum Beispiel in einem alten Projekt, das noch keine pyproject.toml hat. Dann:

uv venv --python 3.12
Using CPython 3.12.11
Creating virtual environment at: .venv
Activate with: .venv\Scripts\activate

Die letzte Zeile stammt aus Windows PowerShell. Hier unterscheiden sich die Betriebssysteme:

# Windows (PowerShell)
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

Ist sie aktiv, beginnt die Eingabeaufforderung mit (hello-ai) oder (.venv), und ein einfaches python führt das Python dieser Umgebung aus. Zum Verlassen: deactivate. Denk daran: Mit uv run braucht man das alles nicht — das ist sein Vorteil. Im README eines Teams uv run zu schreiben ist die sichere Wahl, denn den Zustand „vergessen zu aktivieren“ gibt es dann gar nicht.

Den Editor auf das Python des Projekts zeigen lassen

Das Programm läuft im Terminal, doch der Editor zeigt eine rote Unterstreichung unter import httpx — das heißt fast immer, dass der Editor auf ein anderes Python schaut.

VS Code: Installiere Microsofts Erweiterung Python. Öffne dann den Projektordner, drücke Ctrl + Shift + P (unter macOS Cmd + Shift + P) → Python: Select Interpreter → wähle das Python in .venv. Wenn es nicht aufgelistet wird, nutze Enter interpreter path und gib den Pfad an: .venv\Scripts\python.exe unter Windows, .venv/bin/python unter macOS/Linux.

PyCharm: Settings → Project → Python Interpreter → Add Interpreter → Add Local Interpreter → wähle eine bestehende Umgebung und gib denselben Pfad an. Neuere Versionen bieten außerdem direkt einen Umgebungstyp uv an.

Der einfachste Weg, sicherzugehen, welches Python der Editor benutzt, ist, dieses Skript im eingebauten Terminal des Editors auszuführen:

import sys

print(sys.executable)

Der Pfad sollte in der .venv deines Projekts liegen — zum Beispiel ...\hello-ai\.venv\Scripts\python.exe. Der Anfang des Pfads hängt von deinem Ordner ab; deshalb ist die vollständige Ausgabe hier nicht abgebildet.

Ein vollständiges Beispiel

Erstelle im Projekt hello-ai eine Datei namens env_check.py. Es ist ein kleines Skript zur „Umgebungsprüfung“ — wenn jemand neu in ein Team kommt, bestätigt so ein Lauf zuerst, dass alles dort ist, wo es sein soll:

import sys
from importlib.metadata import version
from pathlib import Path


def main() -> None:
    in_venv = sys.prefix != sys.base_prefix
    print(f"Python      : {sys.version_info.major}.{sys.version_info.minor}")
    print(f"In a venv   : {in_venv}")
    print(f"Env folder  : {Path(sys.prefix).name}")

    import httpx  # installed with `uv add httpx`

    print(f"httpx       : {version('httpx')}")
    print(f"Client ready: {httpx.Client is not None}")
    print("Hello, AI engineer.")


if __name__ == "__main__":
    main()

Starte es aus dem Projekt heraus:

uv run env_check.py

Python      : 3.12
In a venv   : True
Env folder  : .venv
httpx       : 0.28.1
Client ready: True
Hello, AI engineer.

Jetzt führen wir dieselbe Datei in einer leeren Umgebung aus. Die Datei wurde in einen anderen Ordner kopiert, dort mit uv venv --python 3.12 eine Umgebung angelegt und die Datei direkt mit dem Python dieser Umgebung ausgeführt (.venv\Scripts\python env_check.py unter Windows, .venv/bin/python env_check.py unter macOS/Linux):

Python      : 3.12
In a venv   : True
Env folder  : .venv
Traceback (most recent call last):
  File "env_check.py", line 20, in <module>
    main()
  File "env_check.py", line 12, in main
    import httpx  # installed with `uv add httpx`
    ^^^^^^^^^^^^
ModuleNotFoundError: No module named 'httpx'

(Auf deinem Rechner zeigt der Traceback den vollen Pfad der Datei; hier ist nur der Name übrig geblieben.)

Ein paar Entscheidungen in diesem Skript lohnen einen Blick.

sys.prefix != sys.base_prefix — Python selbst weiß, ob es in einer virtuellen Umgebung läuft. sys.base_prefix ist das Basis-Python, aus dem die Umgebung erstellt wurde, und sys.prefix ist das, das gerade läuft. Wenn sie sich unterscheiden, befindest du dich in einer Umgebung.

Der Ordnername statt des vollen Pfads — Path(sys.prefix).name gibt nur den letzten Teil aus, .venv. Der volle Pfad ist auf jedem Rechner anders; der Name ist für alle gleich. Je weniger maschinenspezifisch die Ausgabe eines Prüfskripts ist, desto leichter lässt sie sich im Team-Chat vergleichen.

import httpx mitten in der Funktion — Imports gehören normalerweise an den Anfang einer Datei, und dort sollten sie auch stehen. Hier steht er bewusst in der Mitte, damit in einer leeren Umgebung die ersten drei Zeilen ausgegeben werden, bevor der Fehler kommt. Die Fehlerausgabe erzählt dann ihre eigene Geschichte: Python 3.12 ist in Ordnung, eine Umgebung ist aktiv, aber in dieser Umgebung fehlt httpx. Die Lösung ist uv add httpx — oder, falls die pyproject.toml des Projekts es bereits auflistet, uv sync.

version('httpx') — importlib.metadata ist der Standardweg, die Version eines Pakets auszulesen. Nicht jedes Paket hat ein __version__, aber jedes installierte Paket hat Metadaten.

Wenn es schiefgeht

The term 'uv' is not recognized as the name of a cmdlet, function, script file, or operable program (unter macOS/Linux: uv: command not found) uv ist installiert, aber das Terminal, in dem du tippst, wurde vor der Installation geöffnet und kennt deshalb den neuen PATH nicht. Schließe das Terminal und öffne es neu (in VS Code den ganzen Editor).

error: No pyproject.toml found in current directory or any parent directory Du hast uv add außerhalb eines Projektordners ausgeführt. uv add schreibt in die Projektdatei, und ohne Projekt gibt es nichts, wohin geschrieben werden könnte. Wechsle mit cd in das Projekt, oder führe uv init zuerst aus, wenn es neu ist.

ModuleNotFoundError: No module named 'httpx' Dem Python, das das Skript ausführt, fehlt das Paket. Zwei übliche Ursachen: Das Paket wurde nie mit uv add hinzugefügt, oder das Skript wurde mit einfachem python statt mit uv run gestartet, sodass das System-Python lief statt der Umgebung des Projekts. Starte es mit uv run env_check.py.

error: Failed to spawn: hello.py gefolgt von Caused by: program not found Du hast uv run einen Dateinamen gegeben, der im aktuellen Ordner nicht existiert — meist ein Tippfehler, oder du bist im falschen Ordner. Weil es die Datei nicht findet, sucht uv stattdessen nach einem Programm mit diesem Namen, deshalb wirkt die Meldung seltsam.

× No solution found when resolving dependencies gefolgt von Because htpx was not found in the package registry ... Ein Tippfehler im Paketnamen (htpx). Die gute Nachricht: Ein fehlgeschlagenes uv add ändert nichts — pyproject.toml und uv.lock bleiben, wie sie waren. Korrigiere die Schreibweise und führe den Befehl erneut aus.

.venv\Scripts\activate : File ... cannot be loaded because running scripts is disabled on this system Eine Sicherheitsrichtlinie von PowerShell. Führe einmal Set-ExecutionPolicy -Scope CurrentUser RemoteSigned aus und öffne ein neues Terminal — oder verzichte auf das Aktivieren und führe alles mit uv run aus.

Jetzt bist du dran

Wenn uv und Python 3.12 auf deinem Rechner bereit sind, erstelle ein neues Projekt:

1. Erstelle das Projekt mit uv init my-first-agent --python 3.12 und füge mit uv add httpx ein Paket hinzu
2. Schreib die oben stehende Datei env_check.py genau so ins Projekt und starte sie mit uv run env_check.py
3. Öffne pyproject.toml und zeige, dass httpx unter dependencies steht und dass im Projekt eine Datei uv.lock entstanden ist
4. Öffne das Projekt in VS Code oder PyCharm und wähle die .venv des Projekts als Interpreter aus, damit es bei der Zeile import httpx keine rote Unterstreichung mehr gibt

Erwartete Ausgabe (die httpx-Version kann bei dir neuer sein):

Python      : 3.12
In a venv   : True
Env folder  : .venv
httpx       : 0.28.1
Client ready: True
Hello, AI engineer.

Dann mach es absichtlich kaputt: Führe uv remove httpx aus und danach noch einmal uv run env_check.py. Notiere, bis wohin es ausgibt, welcher Fehler erscheint und was sich in pyproject.toml geändert hat. Repariere es dann mit uv add httpx. Diese Schleife aus Kaputtmachen und Reparieren dauert zwei Minuten, aber in der ersten Woche deines ersten Jobs ist es genau das, was dir am meisten Zeit spart.