# Python, uv und einen Editor einrichten

Martin Schmid mit Claude
·
2026-08-13

Dieses Dokument richtet einen Rechner so ein, dass man mit Python arbeiten kann. Es setzt **keine** Vorkenntnisse voraus: Wer noch nie ein Terminal geöffnet hat, kann hier anfangen.

Es gehört zu den Tageskursen *Schiffe versenken* und *Crack Me*, funktioniert aber auch für sich allein — als Startpunkt für alle, die Python auf ihrem eigenen Rechner ausprobieren wollen.

**Zeitbedarf:** 20–30 Minuten beim ersten Mal.

**Wie du dieses Dokument benutzt:** Lies **Teil 0**, arbeite **einen** der Teile 1–3 durch (deinen Rechner), dann **Teil 4** (Editor) und **Teil 5** (Shell). Die Teile 6 bis 8 sind Nachschlagekapitel — Teil 6 solltest du einmal gelesen haben, bevor du loslegst.

| Teil | Inhalt | für wen |
|---|---|---|
| 0 | Was wir installieren und warum | alle |
| 1 | Windows einrichten | Windows |
| 2 | macOS einrichten | Mac |
| 3 | Linux einrichten | Linux |
| 4 | Der Editor: VSCodium | alle |
| 5 | Die Shell — das Minimum, das trägt | alle |
| 6 | Wo tippe ich das eigentlich ein? | alle, unbedingt |
| 7 | Erste Hilfe | bei Problemen |
| 8 | Der tägliche Ablauf | alle |

## Teil 0 — Was wir installieren und warum

Wir installieren **nicht** Python direkt von python.org, sondern ein Werkzeug namens **uv**. Das klingt nach einem Umweg, ist aber der kürzere Weg:

|  | ohne uv | mit uv |
|---|---|---|
| Python installieren | Installer herunterladen, Haken bei „Add to PATH“ nicht vergessen (Klassiker: vergessen) | `uv python install 3.12` |
| Mehrere Python-Versionen | Konfliktquelle Nummer eins | nebeneinander, kein Konflikt |
| Projektumgebung anlegen | `python -m venv .venv` | `uv venv` |
| Umgebung aktivieren | in **jedem** neuen Fenster erneut | entfällt bei `uv run` |
| Paket installieren | `pip install …` — landet manchmal im falschen Python | `uv pip install …` |

uv braucht **kein** vorinstalliertes Python. Es bringt sich seine Python-Versionen selbst mit, in einen eigenen Ordner im Benutzerverzeichnis, ohne Administratorrechte und ohne am System etwas zu verstellen. Ein bereits vorhandenes Python bleibt unberührt daneben stehen.

> ⚠️ Eine Festlegung vorweg: Wir nehmen Python 3.12. Nicht die neueste Version. Grund: pygame (die Spielebibliothek für beide Kurse) hat für Python 3.14 und 3.15 keine fertigen Pakete. Die Installation versucht dann, pygame aus dem Quellcode zu übersetzen, und scheitert mit einer langen, unverständlichen Fehlermeldung. Mit 3.12 gibt es fertige Pakete, und alles läuft in Sekunden. Deshalb steht in jedem Befehl unten --python 3.12. Das ist kein Tippfehler und keine Nostalgie — es ist die Ursache, aus der die häufigste Installations- katastrophe entsteht.

### Was ist eigentlich eine „Projektumgebung“?

Ein Begriff, der gleich mehrfach vorkommt und den man einmal verstanden haben sollte.

Wenn du ein Paket wie pygame installierst, muss es irgendwo hin. Landet es in der System-Python-Installation, teilen sich **alle** deine Projekte dieselben Pakete — und sobald Projekt A eine andere Version braucht als Projekt B, hast du ein Problem, das sich nicht auflösen lässt.

Eine Projektumgebung (englisch *virtual environment*, kurz *venv*) ist deshalb ein Unterordner im Projekt, meist `.venv` genannt, der eine eigene, abgeschottete Python-Installation enthält. Was du dort hineininstallierst, sieht nur dieses eine Projekt. Löschst du den Ordner, ist alles weg — dein Code bleibt unberührt, denn der liegt in `.py`-Dateien daneben.

Das ist kein Profi-Luxus, sondern der Normalfall. Auf modernen Linux-Systemen verweigert der Rechner die systemweite Installation sogar ausdrücklich (siehe Teil 3).

## Teil 1 — Windows einrichten

### Schritt 1: PowerShell öffnen

Windows-Taste drücken, `powershell` tippen, Enter. Es öffnet sich ein Fenster mit einer Zeile wie:

```
PS C:\Users\DeinName>
```

Dieses `PS ...>` am Anfang der Zeile ist der **Prompt**. Er sagt dir, wo du bist. Merk dir sein Aussehen — in Teil 6 wird das noch wichtig.

Administratorrechte brauchst du **nicht**. Wenn dich jemand auffordert, „als Administrator ausführen“ zu wählen: für diese Anleitung nicht nötig.

### Schritt 2: uv installieren

Diesen Befehl in PowerShell eintippen (oder kopieren und mit Rechtsklick einfügen) und Enter:

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

Der Zusatz `-ExecutionPolicy ByPass` ist nötig, weil Windows das Ausführen von Skripten standardmäßig blockiert. Er gilt nur für diesen einen Befehl und ändert nichts dauerhaft an deinen Einstellungen.

Falls du lieber den Windows-Paketmanager benutzt, geht auch:

```
winget install --id=astral-sh.uv -e
```

### Schritt 3: PowerShell schließen und neu öffnen

**Nicht überspringen.** Der Installer hat uv in deinen Suchpfad eingetragen, aber ein bereits geöffnetes Fenster merkt davon nichts. Fenster zu, neues aufmachen.

**Kontrolle:**

```
uv --version
```

Erwartete Antwort: etwas wie `uv 0.12.3`.

Kommt stattdessen *„Die Benennung „uv“ wurde nicht als Name eines Cmdlets … erkannt“*, hast du Schritt 3 übersprungen oder die Installation lief nicht durch. Fenster wirklich schließen, neues öffnen, nochmal probieren.

### Schritt 4: Python 3.12 installieren

```
uv python install 3.12
```

Das lädt eine eigenständige Python-Version herunter (etwa 30 MB) und legt sie in deinem Benutzerordner ab.

### Schritt 5: Einen Ordner für das Projekt anlegen

```
mkdir C:\Users\$env:USERNAME\Projekte\schiffe
cd C:\Users\$env:USERNAME\Projekte\schiffe
```

> 💡 Nicht in OneDrive. Ordner wie Dokumente oder Desktop werden auf vielen Windows-Rechnern von OneDrive synchronisiert. OneDrive greift auf Dateien zu, während Python sie beschreibt, und produziert dann sporadische, völlig unerklärliche Fehler. Ein Ordner direkt unter C:\Users\DeinName\Projekte ist davon nicht betroffen.

### Schritt 6: Umgebung anlegen und pygame installieren

```
uv venv --python 3.12
uv pip install pygame
```

**Kontrolle:**

```
uv run python -c "import pygame; print(pygame.version.ver)"
```

Erwartete Antwort: eine Versionsnummer wie `2.6.1`, meist mit einer freundlichen Begrüßung der pygame-Gemeinde darüber. Sobald diese Zeile erscheint, ist die Einrichtung fertig — weiter mit **Teil 4 (Editor)**.

## Teil 2 — macOS einrichten

### Schritt 1: Terminal öffnen

`Cmd` + `Leertaste`, `Terminal` tippen, Enter. Der Prompt sieht etwa so aus:

```
deinname@MacBook ~ %
```

Das `%` am Ende ist bei neueren Macs üblich (dort läuft die Shell **zsh**), `$` bei älteren mit **bash**. Für alles in diesem Dokument verhalten sich beide gleich.

### Schritt 2: uv installieren

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

Der Befehl lädt ein Installationsskript herunter und führt es aus. Es installiert nach `~/.local/bin` — also in dein Benutzerverzeichnis, **ohne** `sudo`, ohne Passwort und ohne Eingriff ins System.

> 💡 Warum kein Homebrew? Wenn du Homebrew schon hast, geht auch brew install uv. Nur für uv extra Homebrew zu installieren, lohnt aber nicht — der Installer oben tut dasselbe in einem Bruchteil der Zeit.

### Schritt 3: Terminal schließen und neu öffnen

**Nicht überspringen** — dieselbe Begründung wie unter Windows: Der Suchpfad des offenen Fensters ist veraltet.

**Kontrolle:**

```
uv --version
```

Sagt die Shell `command not found: uv`, wurde `~/.local/bin` nicht in den Suchpfad aufgenommen. Sofort-Abhilfe für das laufende Fenster — der Installer legt dafür eine kleine Hilfsdatei an:

```
source $HOME/.local/bin/env
```

Gibt es diese Datei nicht, tut es auch der direkte Weg:

```
export PATH="$HOME/.local/bin:$PATH"
```

Dauerhaft: Die passende Zeile ans Ende von `~/.zshrc` schreiben (bei bash: `~/.bash_profile`). Danach Terminal neu öffnen.

### Schritt 4: Python 3.12 installieren

```
uv python install 3.12
```

macOS bringt zwar ein eigenes Python mit, aber meist eine ältere Version — und Apple kann es mit jedem Systemupdate austauschen oder entfernen. Ein Projekt, das darauf aufbaut, hört irgendwann ohne dein Zutun auf zu funktionieren. Deshalb die eigene Version.

Auf Apple Silicon (M1 bis M4) lädt uv automatisch die passende ARM-Version. Rosetta wird nicht gebraucht.

### Schritt 5: Projektordner anlegen

```
mkdir -p ~/Projekte/schiffe
cd ~/Projekte/schiffe
```

Die Tilde `~` ist die Kurzschreibweise für dein Benutzerverzeichnis, also `/Users/deinname`. `-p` legt fehlende Zwischenordner gleich mit an.

> 💡 Nicht in iCloud Drive. Schreibtisch und Dokumente werden bei aktiviertem iCloud-Sync synchronisiert. Dieselbe Fehlerquelle wie OneDrive unter Windows: Dateien werden ausgelagert oder gesperrt, während dein Programm sie braucht. ~/Projekte liegt außerhalb.

### Schritt 6: Umgebung anlegen und pygame installieren

```
uv venv --python 3.12
uv pip install pygame
```

**Kontrolle:**

```
uv run python -c "import pygame; print(pygame.version.ver)"
```

Erscheint eine Versionsnummer, ist alles bereit — weiter mit **Teil 4 (Editor)**.

### Mac-spezifische Stolpersteine

| Symptom | Ursache | Lösung |
|---|---|---|
| `command not found: uv` | `~/.local/bin` nicht im Suchpfad | `source $HOME/.local/bin/env`, dauerhaft in `~/.zshrc` |
| „… kann nicht geöffnet werden, da Apple es nicht auf Schadsoftware überprüfen konnte“ | Gatekeeper bei heruntergeladenen Programmen (betrifft den Editor, nicht uv) | Rechtsklick auf das Programm → **Öffnen** → im Dialog nochmals **Öffnen** |
| `xcrun: error: invalid active developer path` | Command Line Tools fehlen (bei manchen Werkzeugen nötig) | `xcode-select --install` |
| Ein altes Projekt läuft plötzlich nicht mehr | Systemupdate hat das Apple-Python ausgetauscht | genau deshalb `uv venv --python 3.12` |

## Teil 3 — Linux einrichten

Die Anleitung gilt für alle gängigen Distributionen. Unterschiede gibt es fast nur beim Nachinstallieren von `curl`.

### Schritt 1: Terminal öffnen

Meist `Strg` + `Alt` + `T`, sonst im Anwendungsmenü nach „Terminal“ suchen. Der Prompt sieht etwa so aus:

```
deinname@rechner:~$
```

Das `$` am Ende bedeutet: normaler Benutzer. Ein `#` stünde für root — dort sollte man **nicht** arbeiten.

### Schritt 2: curl sicherstellen

Meist ist `curl` schon da. Prüfen mit `curl --version`. Falls nicht:

```
# Debian, Ubuntu, Mint, Pop!_OS
sudo apt update && sudo apt install curl

# Fedora
sudo dnf install curl

# Arch, Manjaro
sudo pacman -S curl

# openSUSE
sudo zypper install curl
```

Das ist der **einzige** Schritt, der `sudo` braucht. Alles Weitere läuft ohne Administratorrechte.

### Schritt 3: uv installieren

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

Installiert nach `~/.local/bin`, also ins eigene Benutzerverzeichnis. Kein `sudo`, keine Systemdateien, kein Konflikt mit der Paketverwaltung deiner Distribution — ein Punkt, der auf Linux besonders zählt: Das Python deines Systems gehört dem System, und wer dort hineininstalliert, riskiert kaputte Systemwerkzeuge.

> 💡 Auch möglich: Manche Distributionen haben uv im eigenen Repository (sudo pacman -S uv unter Arch, sudo dnf install uv unter neueren Fedora). Das ist gleichwertig; der Installer oben ist nur überall verfügbar.

### Schritt 4: Terminal neu öffnen

Oder für das laufende Fenster sofort:

```
source $HOME/.local/bin/env      # Hilfsdatei des Installers
```

Falls es die Datei nicht gibt:

```
export PATH="$HOME/.local/bin:$PATH"
```

Dauerhaft gehört die passende Zeile ans Ende von `~/.bashrc` (bzw. `~/.zshrc`).

**Kontrolle:**

```
uv --version
```

### Schritt 5: Python 3.12 installieren

```
uv python install 3.12
```

> 💡 Warum nicht einfach das Python der Distribution? Weil es dem System gehört. Ubuntu, Debian und Fedora benutzen Python für eigene Systemwerkzeuge; was du dort veränderst, kann diese Werkzeuge beschädigen. Deshalb weigern sich aktuelle Distributionen auch, systemweit Pakete zu installieren, und melden stattdessen error: externally-managed-environment (das ist die Regel PEP 668). Diese Meldung ist kein Defekt, sondern ein Schutzmechanismus — und genau der Grund, warum wir mit Projektumgebungen arbeiten. Mit uv umgehst du das Thema komplett, weil weder Python noch die Pakete das System berühren.

### Schritt 6: Projektordner anlegen

```
mkdir -p ~/Projekte/schiffe
cd ~/Projekte/schiffe
```

### Schritt 7: Umgebung anlegen und pygame installieren

```
uv venv --python 3.12
uv pip install pygame
```

**Kontrolle:**

```
uv run python -c "import pygame; print(pygame.version.ver)"
```

Die pygame-Pakete für Linux bringen die benötigte Grafikbibliothek **SDL fertig mit** (die Ausgabe nennt sie beim Start, z. B. `SDL 2.28.4`) — es muss dafür normalerweise **nichts** über die Paketverwaltung nachinstalliert werden.

### Linux-spezifische Stolpersteine

| Symptom | Ursache | Lösung |
|---|---|---|
| `uv: command not found` | `~/.local/bin` nicht im Suchpfad | `source $HOME/.local/bin/env`, dauerhaft in `~/.bashrc` bzw. `~/.zshrc` |
| `error: externally-managed-environment` | systemweite Installation versucht (PEP 668) | in der Projektumgebung arbeiten: `uv pip install …` statt `pip install …` |
| pygame-Fenster bleibt schwarz oder öffnet nicht (Wayland) | SDL wählt den falschen Grafiktreiber | testweise `SDL_VIDEODRIVER=x11 uv run spiel.py` |
| Kein Ton in pygame | ALSA/PulseAudio-Anbindung fehlt | für die Kurse verzichtbar; sonst Audio-Pakete der Distribution nachinstallieren |
| Alles läuft, aber `python` startet Version 3.11 | Distributions-Python im Suchpfad | egal — wir starten grundsätzlich mit `uv run` |

## Teil 4 — Der Editor: VSCodium

Python-Dateien sind reine Textdateien. Du brauchst einen Editor, der das versteht — **nicht** Word, **nicht** WordPad, **nicht** TextEdit im Standardmodus.

### Warum VSCodium und nicht VS Code?

Visual Studio Code von Microsoft ist der verbreitetste Editor für Python. Sein Quellcode steht unter der freizügigen MIT-Lizenz — das Programm, das Microsoft zum Herunterladen anbietet, unterliegt allerdings einer proprietären Produktlizenz, und während des Build-Vorgangs kommen Telemetrie, Microsoft-Branding und die Anbindung an den hauseigenen Erweiterungs-Marktplatz hinzu.

**VSCodium** ist derselbe Quellcode, nur ohne diese Zutaten gebaut: Das Projekt betreibt Build-Skripte, die Microsofts Repository klonen und ohne die proprietäre `product.json` übersetzen — heraus kommt ein Programm, das tatsächlich MIT-lizenziert ist, ohne Telemetrie. Funktional bekommst du dieselbe Oberfläche, dieselben Tastenkürzel, dasselbe integrierte Terminal.

Für einen Einstieg auf dem eigenen Rechner ist das die ehrlichere Variante: Man lernt ein Werkzeug, das man vollständig behalten und weitergeben darf.

### Installation

**Windows:**

```
winget install -e --id VSCodium.VSCodium
```

**macOS:** Mit Homebrew `brew install --cask vscodium`, sonst das `.dmg` von den [GitHub-Releases](https://github.com/VSCodium/vscodium/releases) laden. Beim ersten Start meldet sich womöglich Gatekeeper — dann Rechtsklick auf das Programm, **Öffnen**, und im Dialog nochmals **Öffnen**.

**Linux:** Über die Paketverwaltung, sofern das VSCodium-Repository eingebunden ist; sonst das passende `.deb`, `.rpm` oder AppImage von den GitHub-Releases. Unter Arch: `yay -S vscodium-bin`. Als Flatpak: `flatpak install flathub com.vscodium.codium`.

### Die eine Einschränkung, die du kennen musst

VSCodium darf den Microsoft-Marktplatz nicht benutzen — dessen Nutzungsbedingungen erlauben das nur Microsoft-Produkten. Stattdessen bezieht es Erweiterungen aus der **Open VSX Registry**, einem herstellerneutralen Verzeichnis der Eclipse Foundation.

Praktisch heißt das für Python:

| Erweiterung | in VSCodium? | Bedeutung |
|---|---|---|
| **Python** (`ms-python.python`) | ✅ ja | Syntaxfarben, Ausführen, Debuggen, Interpreter-Auswahl |
| **Pylance** (`ms-python.vscode-pylance`) | ❌ nein, dauerhaft | proprietär, an das offizielle VS Code gebunden |
| **Pyright** / **basedpyright** | ✅ ja | freier Ersatz für die Code-Analyse |
| **Ruff** | ✅ ja | schnelle Stilprüfung, optional |

**Was das konkret kostet:** Pylance liefert die besonders schlauen Autovervollständigungen. Es ist aber nur eine *optionale* Ergänzung — die Python-Erweiterung funktioniert ohne sie vollständig. Für die Kurstage merkst du keinen Unterschied, zumal wir Programme ohnehin mit `uv run` im Terminal starten. Wer später mehr Komfort will, installiert **basedpyright** aus Open VSX.

Wem diese Einschränkung zu lästig ist, nimmt VS Code — auch das ist eine legitime Entscheidung. Die Kursinhalte funktionieren mit beiden Editoren identisch.

### Einrichtung nach der Installation

1. **Erweiterung installieren:** linke Leiste, Symbol mit den vier Quadraten, nach `Python` suchen, installieren.
2. **Ordner öffnen:** *Datei → Ordner öffnen* → dein Projektordner. Nicht die einzelne Datei öffnen, sondern **den Ordner** — nur dann findet der Editor die Projektumgebung.
3. **Interpreter auswählen:** `Strg`+`Shift`+`P` (Mac: `Cmd`+`Shift`+`P`), `Python: Select Interpreter` tippen, den Eintrag mit `.venv` auswählen. Damit weiß der Editor, welches Python zum Projekt gehört.
4. **Integriertes Terminal:** `Strg` + `ö` (bzw. *Ansicht → Terminal*). Es öffnet sich unten im Fenster und steht bereits im richtigen Ordner — dort kannst du direkt `uv run spiel.py` eintippen, ohne das Fenster zu wechseln.

> ⚠️ Die Dateiendungs-Falle. Speicherst du eine Datei mit dem Windows-Editor als test.py, macht Windows stillschweigend test.py.txt daraus. Das Programm startet dann nie, und die Fehlermeldung hilft nicht weiter. In VSCodium passiert das nicht. Falls du doch einmal Notepad benutzt: im Speichern-Dialog bei „Dateityp“ auf Alle Dateien umstellen.

## Teil 5 — Die Shell: das Minimum, das trägt

Die Shell ist das Programm, das im Terminal auf deine Eingaben wartet. Unter Windows heißt sie PowerShell, unter macOS meist zsh, unter Linux meist bash. Sie tut nichts anderes, als Befehle entgegenzunehmen und auszuführen.

Für alles in diesem Dokument reichen **fünf** Befehle.

### Die fünf Befehle

| Zweck | Windows (PowerShell) | macOS / Linux |
|---|---|---|
| Wo bin ich gerade? | `pwd` | `pwd` |
| Was liegt hier? | `dir` (`ls` geht auch) | `ls` |
| Ordner wechseln | `cd Projekte` | `cd Projekte` |
| eine Ebene zurück | `cd ..` | `cd ..` |
| Ordner anlegen | `mkdir schiffe` | `mkdir schiffe` |

Mehr braucht es nicht. `cd` und `dir`/`ls` beantworten zusammen fast jede Frage der Sorte „warum findet er meine Datei nicht?“ — nämlich meistens: weil du im falschen Ordner stehst.

### Pfade lesen

Ein Pfad ist eine Wegbeschreibung im Dateisystem. Zwei Sorten:

- **absolut** — vom Anfang her: `C:\Users\Anna\Projekte\schiffe` bzw. `/home/anna/Projekte/schiffe`
- **relativ** — von hier aus: `schiffe` (Unterordner), `..` (eine Ebene höher), `.` (hier)

Unter macOS und Linux ist `~` die Abkürzung fürs eigene Benutzerverzeichnis: `~/Projekte` bedeutet `/home/anna/Projekte`. Windows benutzt `\` als Trennzeichen, alle anderen `/`.

> 💡 Enthält ein Pfad Leerzeichen, gehört er in Anführungszeichen: cd "Meine Projekte". Sonst versteht die Shell zwei getrennte Angaben. Genau deshalb vermeiden viele Leute Leerzeichen und Umlaute in Projektordnernamen — nicht aus Prinzip, sondern weil es Tipparbeit spart.

### Vier Handgriffe, die den Unterschied machen

**1. Tabulator vervollständigt.** Tippe `cd Proj` und drücke `Tab` — die Shell ergänzt `Projekte`. Das spart nicht nur Zeit: Wenn nichts ergänzt wird, existiert der Ordner nicht oder du stehst woanders. Tab ist damit die schnellste Fehlerdiagnose überhaupt.

**2. Pfeil nach oben holt den letzten Befehl zurück.** Mehrfach drücken blättert weiter zurück. Beim Ausprobieren tippt man denselben Befehl selten zweimal.

**3. Strg + C bricht ab.** Wenn ein Programm läuft und nicht aufhört — hier hört es auf. Das gilt auch für ein hängendes pygame-Fenster.

**4. Kopieren und Einfügen ist anders.** In PowerShell fügt ein **Rechtsklick** ein. Im Mac-Terminal gilt `Cmd`+`V` wie gewohnt. In vielen Linux-Terminals ist es `Strg`+`Shift`+`V` — das normale `Strg`+`V` tut dort nichts, weil `Strg`+`C` und `Strg`+`V` im Terminal seit jeher andere Bedeutungen haben.

### Was du nicht tun solltest

- **Befehle aus dem Internet blind einfügen**, besonders nicht mit `sudo` davor. Das gilt auch für die Befehle in diesem Dokument: Sie stammen von den offiziellen Projektseiten, und du darfst sie nachschlagen.
- **Als root arbeiten** (Prompt endet auf `#`). Für alles hier nicht nötig — der einzige `sudo`-Befehl im ganzen Dokument ist das Nachinstallieren von `curl` unter Linux.

## Teil 6 — Wo tippe ich das eigentlich ein?

**Dieser Abschnitt ist der wichtigste im ganzen Dokument.** Fast jede rätselhafte Fehlermeldung der ersten Tage kommt daher, dass etwas an der richtigen Stelle stand — nur eben im falschen Fenster.

Es gibt **drei Orte**, an denen etwas eingetippt wird. Sie sehen ähnlich aus und verhalten sich völlig verschieden.

### Die drei Orte

|  | Ort 1: **Terminal** | Ort 2: **Python-Konsole** | Ort 3: **Datei** |
|---|---|---|---|
| **Prompt** | `PS C:\...>` (Windows) `… %` / `…$` (Mac, Linux) | `>>>` | keiner |
| **Was dort funktioniert** | `uv`-Befehle, `cd`, `mkdir` | Python-Code, Zeile für Zeile | Python-Code, dauerhaft |
| **Wofür** | installieren, Programm starten | **etwas ausprobieren** | das eigentliche Programm |
| **Bleibt erhalten?** | – | nein, alles weg beim Schließen | ja |

In den Kursunterlagen ist **über jedem Code-Block** vermerkt, welcher der drei Orte gemeint ist:

- 🖥️ **Terminal** — PowerShell bzw. Terminal
- 🐍 **Python-Konsole** — die Zeilen mit `>>>`
- 📄 **Datei** — im Editor schreiben, speichern, dann per Terminal starten

### Die Python-Konsole betreten und wieder verlassen

Die Python-Konsole (auch **REPL** genannt, für *Read-Eval-Print-Loop*: liest eine Zeile, wertet sie aus, gibt das Ergebnis aus, wartet auf die nächste) ist der Ort zum Ausprobieren. Sie startet aus dem Terminal heraus:

🖥️ **Terminal**

```
uv run python
```

Danach ändert sich der Prompt — **das ist das Signal, dass du jetzt woanders bist**:

```
Python 3.12.11 (main, …)
Type "help", "copyright", "credits" or "license" for more information.
>>>
```

Ab hier gilt Python. Jetzt kannst du Sachen ausprobieren und bekommst sofort eine Antwort, ohne irgendetwas zu speichern:

🐍 **Python-Konsole**

```
>>> 2 + 3
5
>>> name = "Kreuzer"
>>> len(name)
7
>>> (3, 5) in {(3, 5), (1, 2)}
True
```

Die Antwort erscheint direkt darunter — ganz ohne `print()`. Das ist der eigentliche Reiz dieses Ortes: Du kannst eine Frage stellen und bekommst sofort Antwort.

**Wieder heraus** kommst du mit:

```
>>> exit()
```

(Alternativ: `Strg` + `Z` und dann Enter unter Windows, `Strg` + `D` unter macOS und Linux.) Der Prompt sieht danach wieder aus wie am Anfang — du bist zurück im Terminal.

> ⚠️ Wichtig: uv run python — nicht einfach python. Nur so landest du in dem Python, in dem auch pygame installiert ist. Tippst du bloß python, öffnet sich unter Windows womöglich der Microsoft Store, und unter macOS oder Linux startet ein anderes, älteres Python, in dem pygame fehlt.

### Ein Programm aus einer Datei starten

Sobald etwas länger als ein paar Zeilen wird, gehört es in eine Datei. Datei im Editor schreiben, speichern (`Strg`+`S`), dann im Terminal:

🖥️ **Terminal**

```
uv run spiel.py
```

Wichtig: Das Terminal muss **in dem Ordner stehen**, in dem die Datei liegt. Mit `cd` wechselst du dorthin, mit `dir` (Windows) bzw. `ls` (Mac, Linux) siehst du, was im aktuellen Ordner liegt. Taucht deine Datei da nicht auf, bist du im falschen Ordner — nicht die Datei ist kaputt.

### Der Kompass: die Fehlermeldung verrät den Ort

Wenn du am falschen Ort tippst, sagt der Rechner das ziemlich deutlich — man muss die Meldung nur zuordnen können:

**Python-Code ins Terminal getippt:**

```
PS C:\...> laenge = 5
Die Benennung "laenge" wurde nicht als Name eines Cmdlets … erkannt.
```

```
… % laenge = 5
zsh: number expected
```

→ *Das war Python. Du bist aber im Terminal.* Mit `uv run python` in die Python-Konsole wechseln.

**Terminal-Befehl in die Python-Konsole getippt:**

```
>>> uv pip install pygame
  File "", line 1
    uv pip install pygame
       ^^^
SyntaxError: invalid syntax
```

→ *Das war ein Terminal-Befehl. Du bist aber in Python.* Mit `exit()` heraus, dann nochmal.

Diese beiden Meldungen wirst du beide mindestens einmal sehen. Das ist kein Zeichen von Unfähigkeit, sondern der normale Weg, an dem man sich die Unterscheidung antrainiert. Der Trick ist, nicht die Meldung zu lesen und zu resignieren, sondern **zuerst auf den Prompt zu schauen**: Steht da `>>>` oder nicht?

## Teil 7 — Erste Hilfe

| Meldung / Symptom | Ursache | Lösung |
|---|---|---|
| `Die Benennung "uv" wurde nicht … erkannt` (Windows) | Terminal nach der Installation nicht neu gestartet | Fenster schließen, neu öffnen |
| `command not found: uv` (Mac, Linux) | `~/.local/bin` nicht im Suchpfad | `source $HOME/.local/bin/env` oder `export PATH="$HOME/.local/bin:$PATH"`, dauerhaft in `~/.zshrc` bzw. `~/.bashrc` |
| Beim Tippen von `python` öffnet sich der **Microsoft Store** | Windows-Platzhalter für nicht installiertes Python | `uv run python` benutzen statt `python` |
| `ModuleNotFoundError: No module named 'pygame'` | Programm läuft in einem anderen Python als dem, in das installiert wurde | mit `uv run spiel.py` starten, nicht mit `python spiel.py` |
| Bei `uv pip install pygame`: lange Fehlermeldung mit `Getting requirements to build wheel … error` | Python-Version zu neu (3.14+), es gibt kein fertiges pygame-Paket | Umgebung mit `uv venv --python 3.12` neu anlegen |
| `error: externally-managed-environment` (Linux) | systemweite Installation versucht (PEP 668) | in der Projektumgebung arbeiten: `uv pip install …` |
| `zsh: number expected` / `… nicht als Name eines Cmdlets erkannt` | Python-Code im Terminal | `uv run python`, dann nochmal |
| `SyntaxError: invalid syntax` bei einem `uv`- oder `cd`-Befehl | Terminal-Befehl in der Python-Konsole | `exit()`, dann nochmal |
| Programm startet nicht, „Datei nicht gefunden“ | falscher Ordner, oder Datei heißt `test.py.txt` | `dir` bzw. `ls` prüfen; Datei im Editor neu speichern |
| `can't open file '…spiel.py': No such file or directory` | Terminal steht im falschen Ordner | mit `cd` in den Projektordner wechseln |
| Fenster von pygame öffnet sich und friert sofort ein | fehlende Ereignisschleife (`pygame.event.get()`) | kein Installationsproblem — siehe Meilenstein 3 im Kurs |
| pygame-Fenster bleibt schwarz (Linux, Wayland) | SDL wählt den falschen Grafiktreiber | `SDL_VIDEODRIVER=x11 uv run spiel.py` |

### Wenn gar nichts mehr geht

Die Umgebung lässt sich gefahrlos wegwerfen und neu bauen — dein eigener Code liegt in `.py`-Dateien und ist davon nicht betroffen:

🖥️ **Terminal**

```
# Windows
Remove-Item -Recurse -Force .venv
uv venv --python 3.12
uv pip install pygame
```

```
# macOS und Linux
rm -rf .venv
uv venv --python 3.12
uv pip install pygame
```

Das dauert keine Minute. Es ist fast immer schneller, als eine kaputte Umgebung zu reparieren — und es ist der eigentliche Sinn von Projektumgebungen: Sie sind Wegwerfware, dein Code ist es nicht.

## Teil 8 — Der tägliche Ablauf

Nach der einmaligen Einrichtung sieht ein Arbeitstag so aus:

🖥️ **Terminal**

```
cd C:\Users\DeinName\Projekte\schiffe    # Mac/Linux: cd ~/Projekte/schiffe
uv run spiel.py
```

Das ist alles. Kein `activate`, kein `source`, keine Aktivierung in jedem neuen Fenster. `uv run` findet den `.venv`-Ordner im aktuellen Verzeichnis von selbst.

Noch kürzer: Im Editor den Projektordner öffnen und das integrierte Terminal benutzen (`Strg` + `ö`) — es steht bereits im richtigen Ordner.

Zum Ausprobieren zwischendurch:

🖥️ **Terminal**

```
uv run python
```

Und ein neues Paket, falls eines dazukommt:

🖥️ **Terminal**

```
uv pip install name-des-pakets
```

## Anhang — Für später: das Projekt reproduzierbar machen

Sobald du ein Projekt an jemanden weitergeben oder auf einem zweiten Rechner fortsetzen willst, lohnt sich die Projektvariante von uv:

🖥️ **Terminal**

```
uv init --bare              # legt pyproject.toml an
uv add pygame               # trägt die Abhängigkeit dort ein und installiert sie
uv run spiel.py
```

`uv add` schreibt die Abhängigkeit in die Datei `pyproject.toml` und legt zusätzlich eine `uv.lock` an, in der die exakten Versionen festgehalten sind. Wer das Projekt später kopiert, tippt nur `uv sync` und bekommt exakt dieselbe Umgebung — bis auf die Nachkommastelle der Versionsnummer. Das funktioniert über Windows, macOS und Linux hinweg mit denselben Befehlen.

Für die ersten Schritte ist das nicht nötig. Für alles, was länger lebt als einen Tag, ist es die halbe Miete.

## Quellen und weiterführende Links

- **uv** — Dokumentation: `docs.astral.sh/uv`, Installationsanleitungen für alle Systeme
- **VSCodium** — Projektseite und Downloads: `github.com/VSCodium/vscodium/releases`; eine gut lesbare deutschsprachige Einordnung findet sich bei [Den's Hub](https://denshub.com/de/vscodium-open-source-vscode/)
- **Open VSX Registry** — der Erweiterungs-Katalog, den VSCodium benutzt: `open-vsx.org`
- **pygame** — Dokumentation und Beispiele: `pygame.org/docs`