Wer lokale Large Language Models betreiben will, ohne sich auf Cloud-Dienste verlassen zu müssen, kommt an text-generation-webui von oobabooga kaum vorbei. Mit über 47.000 GitHub-Stars ist das Projekt der De-facto-Standard für selbstgehostetes LLM-Hosting. Die Gradio-basierte Oberfläche unterstützt die breiteste Palette an Backends – von llama.cpp über ExLlamav2 bis hin zu Transformers – und versteht dabei fast jedes Quantisierungsformat: GGUF, GPTQ, AWQ, EXL2 und HuggingFace-Safetensors. Wer einen Drop-in-Ersatz für die OpenAI-API sucht, findet auch den: Port 5000 spricht das OpenAI-Schema und lässt sich direkt von LangChain, Continue.dev oder dem OpenAI SDK ansprechen. In dieser Anleitung richtest du text-generation-webui plattformneutral per Docker Compose ein – auf einem Linux-Host, einer VM oder einem leistungsstarken NAS mit Docker-Unterstützung.

Voraussetzungen

Docker Engine >= 24.0 mit Compose Plugin v2.17+ (docker compose mit Leerzeichen, nicht das veraltete docker-compose v1) – siehe Docker und Docker Compose auf Linux installieren
Linux-Host, VM oder NAS mit Docker-Unterstützung (x86_64; arm64 ist nicht offiziell unterstützt)
NVIDIA GPU mit CUDA-Support (empfohlen: RTX 3080 oder besser, mindestens 8 GB VRAM) und NVIDIA Container Toolkit auf dem Host – oder AMD GPU mit ROCm oder mindestens 16 GB RAM für CPU-only-Betrieb
Mindestens 20 GB freier Speicherplatz für Image-Build und Modelle (Modelle allein: 4–70 GB je nach Größe)
git und curl auf dem Host installiert
Für HTTPS nach außen: ein Reverse Proxy wie Nginx Proxy Manager oder Traefik – die Grundkonfiguration ist in Traefik als Docker-Reverse-Proxy beschrieben

Schritt 1: Repository klonen und Projektordner vorbereiten

text-generation-webui veröffentlicht keine fertigen Images auf Docker Hub oder GHCR. Der Build läuft lokal aus dem geklonten Repository. Das ist kein Nachteil – es bedeutet nur, dass du das Repo einmalig klonen musst. Für eine NVIDIA-GPU wechselst du danach in den Unterordner docker/nvidia/; für AMD, Intel Arc oder CPU-only existieren analoge Verzeichnisse.

# Repository klonen (einmalig)
git clone https://github.com/oobabooga/text-generation-webui.git
cd text-generation-webui

# Für NVIDIA-GPU:
cd docker/nvidia

# Für AMD (ROCm):
# cd docker/amd

# Für CPU-only:
# cd docker/cpu

# user_data-Verzeichnis anlegen (PFLICHT vor dem ersten Start)
mkdir -p user_data

# .env aus dem Beispiel erstellen
cp ../.env.example .env

Das Verzeichnis user_data/ muss manuell angelegt werden – fehlt es, schlägt der Volume-Mount beim Start fehl. Es enthält später Modelle, Presets, Charaktere, Logs und die zentrale CMD_FLAGS.txt.

Verifizieren: Stelle sicher, dass die folgenden Dateien und Verzeichnisse vorhanden sind:

ls -la
# Erwartete Ausgabe (u. a.):
# drwxr-xr-x  user_data/
# -rw-r--r--  .env
# -rw-r--r--  docker-compose.yml

Schritt 2: .env anpassen

Die wichtigste Einstellung ist TORCH_CUDA_ARCH_LIST: Dieser Wert muss exakt zur CUDA Compute Capability deiner GPU passen. Ist er falsch, bricht der Build mit CUDA-Kompilierungsfehlern ab. Die Werte für gängige Consumer-GPUs:

GPU-Serie	TORCH_CUDA_ARCH_LIST
NVIDIA RTX 3080 / 3090	8.6
NVIDIA RTX 4080 / 4090	8.9+PTX
NVIDIA RTX 4060 / 4070	8.9
NVIDIA A100	8.0

Den genauen Wert für deine GPU findest du auf https://developer.nvidia.com/cuda-gpus. Öffne die .env und passe die relevanten Zeilen an:

# .env – wichtige Werte
# PFLICHT: CUDA Compute Capability der eigenen GPU anpassen!
TORCH_CUDA_ARCH_LIST=8.6

# Ports (optional, Standard 7860 / 5000)
HOST_PORT=7860
CONTAINER_PORT=7860
HOST_API_PORT=5000
CONTAINER_API_PORT=5000

# Dateiberechtigungen auf Linux (eigene GID eintragen: id -g)
APP_RUNTIME_GID=1000

# Extensions beim Build kompilieren (optional, leer lassen für Standard)
BUILD_EXTENSIONS=

Verifizieren: Zeige die gesetzten Werte ohne Leerzeilen an und prüfe, ob TORCH_CUDA_ARCH_LIST korrekt gesetzt ist:

grep -v '^#' .env | grep -v '^$'
# Erwartete Ausgabe enthält u. a.:
# TORCH_CUDA_ARCH_LIST=8.6

Schritt 3: Image bauen

Der Build kompiliert PyTorch-Erweiterungen und CUDA-Kernel – das dauert beim ersten Mal 20 bis 60 Minuten. Nicht unterbrechen; der Fortschritt lässt sich mit docker compose logs -f beobachten (in einem zweiten Terminal).

# Im Verzeichnis docker/nvidia/ (oder amd/cpu/intel/)
docker compose build

Wer den Build nicht abwarten möchte oder eine einfachere Alternative sucht, kann stattdessen das Community-Image verwenden – dazu mehr im Abschnitt „Häufige Fragen".

Verifizieren: Nach dem erfolgreichen Build erscheint das Image in der lokalen Registry:

docker images | grep text-generation-webui
# Erwartete Ausgabe (Beispiel):
# text-generation-webui-textgen   latest   a1b2c3d4e5f6   5 minutes ago   12.4GB

Schritt 4: Container starten

Das Repository bringt eine fertige docker-compose.yml mit, die alle GPU-Ressourcen, Volumes und Ports bereits korrekt verdrahtet. Wirf einen Blick auf die wichtigsten Eckdaten:

Parameter	Wert	Hinweis
Image	Lokaler Build aus Repo	Kein fertiges Hub-Image
Port 7860	Gradio Web-UI	Immer aktiv
Port 5000	OpenAI-kompatible API	Nur mit `--api` aktiv
Volume	`./user_data`	Modelle, Configs, Logs
GPU	nvidia / amd / cpu	Je nach Variante
Restart	unless-stopped	Neustart nach Reboot

Die vollständige docker-compose.yml für NVIDIA sieht so aus:

version: "3.3"

services:
  textgen:
    build:
      context: .
      args:
        TORCH_CUDA_ARCH_LIST: ${TORCH_CUDA_ARCH_LIST:-8.6;8.9+PTX}
        BUILD_EXTENSIONS: ${BUILD_EXTENSIONS:-}
        APP_GID: ${APP_GID:-6972}
        APP_UID: ${APP_UID:-6972}
    env_file: .env
    user: "${APP_RUNTIME_UID:-6972}:${APP_RUNTIME_GID:-6972}"
    ports:
      - "${HOST_PORT:-7860}:${CONTAINER_PORT:-7860}"
      - "${HOST_API_PORT:-5000}:${CONTAINER_API_PORT:-5000}"
    stdin_open: true
    tty: true
    volumes:
      - ./user_data:/home/app/textgen/user_data
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Starte den Container im Hintergrund:

docker compose up -d

Verifizieren: Prüfe den Container-Status und die Logs:

docker compose ps
# Erwartete Ausgabe:
# NAME        IMAGE          COMMAND   SERVICE   STATUS    PORTS
# textgen     textgen-...    ...       textgen   Up        0.0.0.0:7860->7860/tcp

docker compose logs --tail=30
# Erwartete Ausgabe am Ende:
# Loading the extension "gallery"...
# Running on local URL:  http://0.0.0.0:7860

Schritt 5: Web-UI öffnen und erstes Modell laden

Öffne deinen Browser und rufe http://<HOST-IP>:7860 auf. Beim ersten Start ist noch kein Modell geladen – du siehst die Gradio-Oberfläche mit leeren Tabs.

Um ein Modell zu laden, klicke oben auf den Tab „Model" und gib eine HuggingFace-Repo-ID ein, zum Beispiel:

TheBloke/Mistral-7B-Instruct-v0.2-GGUF – kompaktes 7B-Modell im GGUF-Format, läuft auch mit 8 GB VRAM
TheBloke/Llama-2-13B-chat-GGUF – für 16+ GB VRAM

Klicke auf „Download" und warte, bis das Modell in user_data/models/ gespeichert ist. Danach wählst du es in der Dropdown-Liste aus und klickst auf „Load". Sobald der Ladebalken durchgelaufen ist, wechselst du in den Tab „Chat" und kannst direkt mit dem Modell sprechen.

Alternativ kannst du Modelldateien manuell nach user_data/models/<Modellname>/ kopieren – der Container erkennt sie beim nächsten Laden automatisch.

Verifizieren: Rufe die Web-UI im Browser auf und prüfe, ob sie korrekt lädt:

curl -I http://localhost:7860
# Erwartete Ausgabe:
# HTTP/1.1 200 OK
# content-type: text/html; charset=utf-8

Schritt 6: OpenAI-kompatible API aktivieren

Die API auf Port 5000 ist standardmäßig deaktiviert. Um sie dauerhaft zu aktivieren, ohne den Container neu bauen zu müssen, trägst du das Flag in CMD_FLAGS.txt ein. Diese Datei liegt im persistenten user_data/-Verzeichnis und wird bei jedem Start eingelesen:

# CMD_FLAGS.txt anlegen/bearbeiten
echo "--api --listen" > user_data/CMD_FLAGS.txt

# Container neu starten damit die Flags wirken
docker compose restart

Die API ist anschließend unter http://<HOST-IP>:5000/v1 erreichbar und spricht das OpenAI-Schema. Du kannst sie als Drop-in-Ersatz in LangChain, Continue.dev oder direkt mit dem OpenAI Python SDK verwenden – vollständig lokal, ohne Cloud-Anbindung. Wer damit eigene RAG-Pipelines aufbauen möchte, findet weiterführende Hinweise in der Anleitung zu lokalen RAG-Systemen mit Qdrant.

Verifizieren: Sende eine einfache Anfrage an die API:

curl http://localhost:5000/v1/models
# Erwartete Ausgabe: JSON mit geladenen Modellen
# {"object":"list","data":[{"id":"Mistral-7B-Instruct...","object":"model",...}]}

curl http://localhost:5000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"","messages":[{"role":"user","content":"Hallo!"}],"max_tokens":50}'
# Erwartete Ausgabe: JSON mit "choices" und Modellantwort

Schritt 7: Updates und Backup

Da text-generation-webui lokal gebaut wird, läuft ein Update über git pull und anschließenden Rebuild:

# Ins Repository-Root-Verzeichnis wechseln
cd /pfad/zu/text-generation-webui

# Neue Version holen
git pull

# Zurück in den Varianten-Ordner und neu bauen
cd docker/nvidia
docker compose build --no-cache
docker compose up -d

Alle Modelle, Einstellungen und Charaktere liegen in user_data/ – dieses Verzeichnis ist dein einziges Backup-Target. Ein einfaches rsync oder die 3-2-1-Backup-Strategie genügen, um alles zu sichern.

Beim Community-Image (atinoda/text-generation-webui) läuft das Update einfacher:

docker compose pull
docker compose up -d

Verifizieren: Prüfe nach dem Update, dass der Container wieder läuft:

docker compose ps
# STATUS: Up (running)

docker compose logs --tail=10
# Keine Fehlermeldungen zu fehlenden Modulen oder CUDA-Fehler

Troubleshooting / Typische Fehler

Build bricht mit CUDA-Kompilierungsfehler ab: TORCH_CUDA_ARCH_LIST in .env stimmt nicht mit der GPU überein. Wert auf https://developer.nvidia.com/cuda-gpus nachschlagen und anpassen, dann docker compose build --no-cache erneut ausführen.
„could not select device driver nvidia": Das NVIDIA Container Toolkit ist nicht installiert oder der Docker-Daemon wurde nach der Installation nicht neu gestartet. Installation: apt install nvidia-container-toolkit && systemctl restart docker (Ubuntu/Debian).
Container startet nicht / Volumes leer: Das Verzeichnis user_data/ wurde nicht angelegt. Lösung: mkdir -p user_data im Compose-Verzeichnis ausführen.
Port 7860 bereits belegt: Ein anderer Dienst nutzt diesen Port. HOST_PORT=7861 in .env setzen und Container neu starten.
Berechtigungsfehler in user_data/ (Linux): Der Container kann keine Dateien schreiben. APP_RUNTIME_GID in .env auf die eigene GID setzen (id -g liefert den Wert), danach docker compose up -d.
API auf Port 5000 nicht erreichbar: --api fehlt in user_data/CMD_FLAGS.txt. Eintrag ergänzen und docker compose restart ausführen.
Modell-Download schlägt fehl (gated Models): HuggingFace-Token fehlt. Token in den Web-UI-Einstellungen unter „Hugging Face" eintragen oder als Umgebungsvariable HF_TOKEN in die .env aufnehmen.
Build dauert extrem lange oder hängt: Normaler Vorgang bei der ersten CUDA-Kompilierung (20–60 Minuten). Nicht abbrechen; Fortschritt in einem zweiten Terminal mit docker compose logs -f beobachten.
docker-compose: command not found oder Syntax-Fehler: Du verwendest das veraltete docker-compose v1. Pflicht ist docker compose (mit Leerzeichen) als Plugin in Version 2.17+.

Häufige Fragen

Welche Modelle werden unterstützt?

Alle gängigen Open-Source-LLMs im GGUF-, GPTQ-, AWQ-, EXL2- und HuggingFace-Safetensors-Format – darunter LLaMA 3, Mistral, Qwen, Phi, Gemma und Falcon. Der Download läuft direkt über die Web-UI im Tab „Model": HuggingFace-Repo-ID eingeben, Modell-Datei auswählen, herunterladen.

Was ist der Unterschied zwischen offiziellem Build und dem atinoda-Community-Image?

Das offizielle Projekt veröffentlicht keine fertigen Images – du baust lokal. Das Community-Image atinoda/text-generation-webui (100.000+ Pulls, zuletzt April 2026) ist ein Wrapper mit identischem Funktionsumfang als fertiges Image. Vorteil des Community-Images: kein Build-Schritt nötig. Nachteil: etwas zeitverzögerter als das Upstream-Repo. Für einen schnellen Einstieg ohne Build-Aufwand:

version: "3.3"
services:
  textgen:
    image: atinoda/text-generation-webui:default-nvidia
    # CPU-only: atinoda/text-generation-webui:default-cpu
    environment:
      - EXTRA_LAUNCH_ARGS=--verbose --listen --api
    ports:
      - "7860:7860"
      - "5000:5000"
      - "5005:5005"
    volumes:
      - ./config:/app/user_data
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Kann ich text-generation-webui ohne GPU (CPU-only) betreiben?

Ja: docker/cpu/docker-compose.yml verwenden. Die Inferenz ist deutlich langsamer als auf einer GPU, aber funktional – llama.cpp ist speziell für CPU-Betrieb optimiert. Empfehlenswert sind mindestens 16 GB RAM; mit 32 GB laufen 7B-Modelle in guter Qualität.

Ist AMD-GPU-Betrieb möglich?

Ja, über docker/amd/docker-compose.yml mit ROCm-kompatiblen GPUs (RX 6000/7000-Serie). ROCm muss auf dem Host installiert sein; das Projekt beschreibt den AMD-Weg als experimentell.

Wie nutze ich text-generation-webui als OpenAI-API-Ersatz?

Nach dem Aktivieren der API (Schritt 6) zeigst du LangChain, Continue.dev oder dem OpenAI Python SDK einfach auf http://<HOST-IP>:5000/v1 und setzt einen beliebigen API-Key (der wird nicht geprüft, sofern du keine Authentifizierung konfigurierst). Das ist besonders nützlich, um bestehende Skripte oder Tools ohne Code-Änderungen mit einem lokalen Modell zu betreiben.

Wie viel Speicherplatz brauche ich?

Das Docker-Image nach dem Build belegt je nach Variante 10–15 GB. Modelle kommen obendrauf: Ein 7B-Modell in Q4-Quantisierung (GGUF) belegt ca. 4–5 GB, ein 13B-Modell ca. 8–10 GB, ein 70B-Modell 40–70 GB. Stelle sicher, dass user_data/ auf einem Laufwerk mit ausreichend Platz liegt – am besten nicht auf dem System-Volume.

Fazit

text-generation-webui ist die flexibelste Wahl, wenn du lokale LLMs mit maximaler Format- und Backend-Kompatibilität betreiben willst. Der Docker-Weg erfordert einmalig einen längeren Build, gibt dir dafür aber vollständige Kontrolle und eine saubere Trennung zwischen Image und Daten. Mit dem user_data/-Volume bleiben alle Modelle und Einstellungen build-übergreifend erhalten; die CMD_FLAGS.txt ermöglicht persistente Konfiguration ohne Rebuild. Für Teams oder Entwickler, die einen lokalen OpenAI-API-Ersatz brauchen, ist Port 5000 der schnellste Weg, bestehende Tools auf eigene Hardware umzubiegen – vollständig privat, ohne Datenweitergabe an Cloud-Dienste.

Wer neben text-generation-webui auch andere LLM-Server-Ansätze kennenlernen möchte: Ollama mit Open WebUI ist der einsteigerfreundlichste Weg, vLLM für offene LLMs die leistungsstärkste Option für Produktiv-Deployments. Für den Aufbau einer vollständigen RAG-Pipeline empfiehlt sich ein Blick auf LocalAI als OpenAI-kompatibler KI-Server.

Weiterführende Anleitungen und Quellen

Offizielle Dokumentation: text-generation-webui GitHub Repository | Docker-Dokumentation (docs/09 - Docker.md) | atinoda/text-generation-webui auf Docker Hub