GUIDE‐Quickstart

Letztes Update: 04. Februar 2026

Inhalt

1. Wozu Quickstart-Bereitstellung?
2. Grundprinzip
3. Struktur im Repository
4. Quickstart für Windows (.bat)
5. Quickstart für Linux / macOS (.sh)
6. Dokumentation der Quickstart-Skripte
7. Best Practices
8. Troubleshooting & typische Fehler
9. Weiterführende Links

Wozu Quickstart-Bereitstellung?

Ziel: Ein neuer Nutzer soll das Projekt mit so wenig Schritten wie möglich lokal starten können – idealerweise durch einen Doppelklick (Windows) oder einen Befehl im Terminal (Linux/macOS).

Typische Ziele:

1. Schneller Einstieg: Neue Studierende / Teammitglieder brauchen kein Vorwissen zu venv, pip, etc.
2. Reproduzierbare Umgebung: Alle nutzen denselben Setup-Prozess (PEP-/PyPA-konform; pyproject.toml, .venv).
3. OS-unabhängigkeit: Primär Windows (Batch), optional ergänzend POSIX-Shell (.sh) für Linux/macOS.

---

Grundprinzip

Ein Quickstart-Skript soll:

1. Idempotent sein
   – mehrmaliges Ausführen darf nichts kaputt machen (nur updaten).

2. Automatisch:

   • Virtuelle Umgebung (.venv) erzeugen, falls nicht vorhanden
   • Abhängigkeiten (aus pyproject.toml) (ggf. via uv oder pip) installieren
   • optional: Lock-File (pylock.toml / uv.lock) respektieren
   • das eigentliche Programm oder eine Demo starten

3. Sichtbar dokumentiert werden
   – in einer lokalen README im Projekt.

---

Struktur im Repository

Empfohlene Struktur:

myproject/
├── src/
│   └── myproject/
│       └── __init__.py
├── quickstart.bat        # Quickstart fuer Windows
├── quickstart.sh         # Optional: Quickstart fuer Linux/macOS
├── README.md             # Projekt-README (funktional)
├── pyproject.toml        # PEP 621 – Abhängigkeiten & Metadaten
├── pylock.toml           # Optional: Lock-File (PEP 751)
└── .venv/                # Wird automatisch erstellt (nicht committen)

Merke: Quickstart-Skripte liegen im Projekt-Root, damit sie einfach zu finden und auszuführen sind.

---

Quickstart fuer Windows (.bat)

Auf Windows ist das Ziel:

Nutzer lädt das Repo → entpackt → Doppelklick auf quickstart.bat → Projekt läuft.

Aufgaben des Batch-Skripts:

1. Python-Version prüfen (optional: Mindestversion aus pyproject.toml auslesen / im Kommentar erwähnen)
2. Virtuelle Umgebung .venv anlegen (falls nicht vorhanden)
3. .venv aktivieren
4. Abhängigkeiten installieren
   • bevorzugt über uv (falls vorhanden)
   • sonst Fallback auf python -m pip
5. Startkommando ausführen (z.B. python -m myproject oder python src/myproject/main.py)

Beispiel quickstart.bat

Minimalbeispiel mit Fallback auf pip

@echo off
setlocal

echo [Quickstart] Python-Projekt wird vorbereitet...

REM 1) Pruefen, ob python verfuegbar ist
python --version >NUL 2>&1
if errorlevel 1 (
    echo [Fehler] Python ist nicht im PATH. Bitte Python 3.10+ installieren.
    pause
    exit /b 1
)

REM 2) Virtuelle Umgebung .venv erstellen (falls noetig)
if not exist ".venv" (
    echo [Quickstart] Erzeuge virtuelle Umgebung (.venv) ...
    python -m venv .venv
)

REM 3) venv aktivieren
call ".venv\Scripts\activate.bat"

REM 4) Paketmanager bestimmen: zuerst uv, sonst pip
where uv >NUL 2>&1
if %errorlevel%==0 (
    echo [Quickstart] Verwende uv fuer Installation ...
    uv sync --frozen || (
        echo [Warnung] uv sync fehlgeschlagen, versuche pip...
        goto :pip_fallback
    )
) else (
    echo [Quickstart] uv nicht gefunden, verwende pip ...
    goto :pip_fallback
)

goto :run_app

:pip_fallback
python -m pip install --upgrade pip
python -m pip install -e .[dev]

:run_app
echo.
echo [Quickstart] Starte Anwendung...
REM Hier das eigentliche Startkommando anpassen:
python -m myproject

echo.
echo [Quickstart] Beendet.
pause
endlocal

Hinweis:

• Das Skript geht davon aus, dass pyproject.toml vorhanden ist und das Paket myproject heißt.
• Falls dein CLI-Entry-Point über pyproject.toml definiert ist (z.B. myproject-cli), kannst du im Block :run_app einfach myproject-cli aufrufen.

Hinweis zu Windows & Aktivierung der virtuellen Umgebung:
Der Schritt

call ".venv\Scripts\activate.bat"

funktioniert auf den meisten Systemen. Auf einigen Windows-Installationen (insbesondere mit restriktiven Execution Policies oder wenn PowerShell als Standard genutzt wird) kann dieser Befehl jedoch fehlschlagen.

In diesem Fall kann die virtuelle Umgebung stattdessen manuell in PowerShell aktiviert werden:

.\.venv\Scripts\Activate.ps1

Falls dabei eine Sicherheitswarnung erscheint, muss ggf. die Execution Policy angepasst werden (z. B. temporär mit:

Set-ExecutionPolicy -Scope Process RemoteSigned
```).

---

Quickstart fuer Linux / macOS (.sh)

Für POSIX-Systeme reicht typischerweise ein Shell-Skript.
Es sollte dieselben Schritte wie quickstart.bat ausführen, aber in Bash/Zsh-Syntax.

Beispiel quickstart.sh

Minimalbeispiel (Bash)

#!/usr/bin/env bash
set -euo pipefail

echo "[Quickstart] Python-Projekt wird vorbereitet ..."

# 1) Python prüfen
if ! command -v python &>/dev/null; then
  echo "[Fehler] 'python' nicht gefunden. Bitte Python 3.10+ installieren."
  exit 1
fi

# 2) Virtuelle Umgebung erstellen
if [ ! -d ".venv" ]; then
  echo "[Quickstart] Erzeuge virtuelle Umgebung (.venv) ..."
  python -m venv .venv
fi

# 3) venv aktivieren
# shellcheck disable=SC1091
source .venv/bin/activate

# 4) Paketmanager: uv bevorzugen
if command -v uv &>/dev/null; then
  echo "[Quickstart] Verwende uv fuer Installation ..."
  if ! uv sync --frozen; then
    echo "[Warnung] uv sync fehlgeschlagen, versuche pip..."
    python -m pip install --upgrade pip
    python -m pip install -e ".[dev]"
  fi
else
  echo "[Quickstart] uv nicht gefunden, verwende pip ..."
  python -m pip install --upgrade pip
  python -m pip install -e ".[dev]"
fi

# 5) Anwendung starten
echo
echo "[Quickstart] Starte Anwendung ..."
python -m myproject
echo
echo "[Quickstart] Beendet."

Benutzung:

chmod +x quickstart.sh
./quickstart.sh

---

Dokumentation der Quickstart-Skripte

Damit der Quickstart nicht „magisch“ wirkt, sondern mithilfe dieses Wiki-Eintrages nachvollziehbar bleibt:

1. README im Repository

   • Kurzer Abschnitt „Installation / Quickstart“
   • Verweis auf quickstart.bat / quickstart.sh
   • Minimaler manueller Weg als Fallback (venv + pip install -e .)

2. Kommentare im Skript

   • Wichtige Schritte knapp kommentieren („warum“, nicht „was“).

---

Best Practices

• Einheitliche Pfade:

  • Verwende immer .venv im Projekt-Root (siehe Pythonprojekt-Standards).

• Keine geheimen Informationen im Skript:

  • API-Keys, Passwörter etc. gehören in .env.

• Fehlertoleranz:

  • verständliche Fehlermeldungen ausgeben („Python nicht gefunden“, „Internetverbindung?“).
  • Exit-Codes setzen (exit /b 1`, `exit 1) – wichtig für CI.

• Idempotenz:

  • .venv nur erstellen, wenn nicht vorhanden.
  • uv sync --frozen oder Lock-File nutzen statt „blind“ neu zu installieren.

• Plattform-Checks vermeiden, wo es geht:

  • Lieber zwei kleine Skripte (.bat` + `.sh) als ein riesiges „Cross-Plattform-Monster“.

---

Troubleshooting & typische Fehler

Python nicht im PATH

• Symptom: Das Skript meldet python wird nicht erkannt / command not found.
• Lösung:
  • Python 3.10+ installieren
  • Bei Windows: Installer-Option „Add python.exe to PATH“ aktivieren
  • Terminal neu starten, dann Quickstart erneut ausführen.

Fehler bei Paketinstallation

• Prüfen, ob Internetzugang besteht.
• Lock-File evtl. kurz ignorieren:
  • .venv löschen
  • quickstart.bat / .sh erneut ausführen
• Falls ein bestimmtes Paket Probleme macht, dessen Version in pyproject.toml fixieren und Lock-File neu erzeugen.

Anwendung startet, aber findet Module nicht

• Stelle sicher, dass das Paket in pyproject.toml mit dem richtigen Namen eingetragen ist (name = "myproject").
• Bei src/-Layout: tool.setuptools.package-dir korrekt setzen.
• Starte die Anwendung bevorzugt als Modul (python -m myproject) statt python src/myproject/main.py.