Zum Hauptinhalt springen
S-EDV news
← Alle Anleitungen
📘 Anleitung Künstliche Intelligenz 18.08.2026 · 9 min Lesezeit Geprüft 30.09.2026

text-generation-webui mit Docker installieren: Umfassende Web-UI für lokale LLMs (llama.cpp, ExLlama, Transformers)

text-generation-webui betreibt lokale LLMs in den Formaten GGUF, GPTQ, AWQ und EXL2 mit optionaler OpenAI-kompatibler API. Die Anleitung zeigt den Docker-Weg vom Repository-Clone bis zum ersten Chat, mit Ports nur auf localhost und API-Key.

Werbung Mit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen. Mehr dazu

Titelbild: text-generation-webui mit Docker, Modelle, Chat, GPU

Wer lokale Large Language Models betreiben will, ohne sich auf Cloud-Dienste verlassen zu müssen, findet in text-generation-webui von oobabooga (Repository inzwischen unter oobabooga/textgen) eine weit verbreitete Lösung. Die Gradio-Oberfläche unterstützt Backends wie llama.cpp, ExLlamaV2 und Transformers sowie die Formate GGUF, GPTQ, AWQ, EXL2 und Safetensors. Port 5000 bietet optional eine OpenAI-kompatible API für LangChain, Continue.dev oder das OpenAI SDK. Diese Anleitung richtet text-generation-webui per Docker Compose auf einem Linux-Host oder einer VM ein.

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 bis 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. Für eine NVIDIA-GPU wechseln Sie nach dem Klonen in docker/nvidia/; für AMD, Intel Arc (Beta) und CPU-only gibt es analoge Verzeichnisse. Die alte Repository-URL leitet GitHub auf oobabooga/textgen weiter.

# 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

Legen Sie user_data/ vor dem Start selbst an. Fehlt es, erzeugt Docker es beim Start als root-eigenes Verzeichnis, in das der Container nicht schreiben kann. Es enthält später Modelle, Presets, Charaktere, Logs und die zentrale CMD_FLAGS.txt.

Die folgenden Dateien und Verzeichnisse sind vorhanden:

$ 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 zur CUDA Compute Capability Ihrer GPU passen. Ist er falsch, bricht der Build mit CUDA-Kompilierungsfehlern ab. Die Werte für gängige Consumer-GPUs:

GPU-SerieTORCH_CUDA_ARCH_LIST
NVIDIA RTX 3080 / 30908.6
NVIDIA RTX 4080 / 40908.9+PTX
NVIDIA RTX 4060 / 40708.9
NVIDIA A1008.0

Den Wert Ihrer GPU liefert nvidia-smi --query-gpu=name,compute_cap --format=csv oder https://developer.nvidia.com/cuda-gpus. Passen Sie die .env an. Die Ports binden Sie über die Hostseite an 127.0.0.1, da die Web-UI keine Anmeldung hat:

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

# Ports: nur lokal erreichbar (Zugriff von außen per Reverse Proxy oder SSH-Tunnel)
HOST_PORT=127.0.0.1:7860
CONTAINER_PORT=7860
HOST_API_PORT=127.0.0.1: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=

Die gesetzten Werte enthalten Ihren TORCH_CUDA_ARCH_LIST-Wert:

$ 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; den Fortschritt zeigt die Ausgabe von docker compose build selbst.

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

Ohne Build nutzen Sie das Community-Image (siehe „Häufige Fragen“).

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

$ docker images | grep textgen
# Erwartete Ausgabe (Beispiel, Name nach Projektordner):
# nvidia-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. Die wichtigsten Eckdaten:

ParameterWertHinweis
ImageLokaler Build aus RepoKein fertiges Hub-Image
Port 7860Gradio Web-UIImmer aktiv
Port 5000OpenAI-kompatible APINur mit --api aktiv
Volume./user_dataModelle, Configs, Logs
GPUnvidia / amd / cpuJe nach Variante
Restartunless-stoppedNeustart nach Reboot

Die docker-compose.yml für NVIDIA aus dem Repository; die Zeile restart: unless-stopped ergänzen Sie selbst, sie fehlt im Original:

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]

Starten Sie den Container im Hintergrund:

$ docker compose up -d

Container-Status und Logs zeigen einen laufenden Dienst:

$ docker compose ps
# Erwartete Ausgabe:
# NAME        IMAGE          COMMAND   SERVICE   STATUS    PORTS
# nvidia-textgen-1   nvidia-textgen   ...   textgen   Up   127.0.0.1:7860->7860/tcp
$ docker compose logs --tail=30
# Erwartete Ausgabe am Ende (im Container):
# Running on local URL:  http://0.0.0.0:7860

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

Rufen Sie http://localhost:7860 auf, von einem anderen Rechner per SSH-Tunnel (ssh -L 7860:127.0.0.1:7860 benutzer@host). Beim ersten Start ist kein Modell geladen.

Öffnen Sie den Tab „Model“ und geben Sie eine Hugging-Face-Repo-ID ein, zum Beispiel:

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

Klicken Sie auf „Download“ und warten Sie, bis das Modell in user_data/models/ liegt. Wählen Sie es in der Liste aus, klicken Sie auf „Load“ und wechseln Sie in den Tab „Chat“.

Alternativ kopieren Sie Modelldateien nach user_data/models/<Modellname>/; sie erscheinen beim nächsten Laden der Liste.

Die Web-UI antwortet, und im Chat-Tab liefert das geladene Modell eine Antwort:

$ 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. Sie aktivieren sie dauerhaft über CMD_FLAGS.txt im persistenten user_data/-Verzeichnis. Setzen Sie mit --api-key einen Schlüssel, sonst nimmt die API Anfragen ohne Prüfung an:

# CMD_FLAGS.txt anlegen/bearbeiten
$ echo "--api --listen --api-key $(openssl rand -hex 24)" > user_data/CMD_FLAGS.txt
$ cat user_data/CMD_FLAGS.txt   # Schlüssel notieren
# Container neu starten damit die Flags wirken
$ docker compose restart

Die API ist anschließend unter http://127.0.0.1:5000/v1 erreichbar und spricht das OpenAI-Schema, etwa für LangChain, Continue.dev oder das OpenAI Python SDK. Wer damit eigene RAG-Pipelines aufbauen möchte, findet weiterführende Hinweise in der Anleitung zu lokalen RAG-Systemen mit Qdrant.

Die API antwortet mit dem Schlüssel (IHR-API-KEY ersetzen):

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

curl http://localhost:5000/v1/chat/completions \
  -H "Authorization: Bearer IHR-API-KEY" \
  -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/. Sichern Sie dieses Verzeichnis. 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

Der Container läuft nach dem Update wieder:

$ 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 fehlt oder ist nicht für Docker konfiguriert. Nach der Installation laut NVIDIA-Installationsanleitung (Paketquelle einrichten, nvidia-container-toolkit installieren) führen Sie sudo nvidia-ctk runtime configure --runtime=docker und sudo systemctl restart docker aus.

Schreibfehler in user_data/ nach dem ersten Start

Das Verzeichnis fehlte und wurde von Docker als root angelegt. Lösung: Container stoppen, sudo chown -R $(id -u):$(id -g) user_data, APP_RUNTIME_GID prüfen, neu starten.

Port 7860 bereits belegt

Ein anderer Dienst nutzt diesen Port. HOST_PORT=127.0.0.1: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, oder die Anfrage enthält nicht den Schlüssel aus --api-key (HTTP 401/403). 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 bis 60 Minuten). Nicht abbrechen; der Fortschritt steht in der Ausgabe von docker compose build.

docker-compose: command not found oder Syntax-Fehler

Das veraltete docker-compose v1 ist im Einsatz. 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“: Hugging-Face-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, Sie bauen lokal. Das Community-Image atinoda/text-generation-webui ist ein fertiges Image ohne Build-Schritt, folgt dem Upstream-Projekt aber mit Verzögerung. Beispiel mit Ports nur auf 127.0.0.1:

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:
      - "127.0.0.1:7860:7860"
      - "127.0.0.1:5000:5000"
      - "127.0.0.1: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 Schritt 6 tragen Sie in LangChain, Continue.dev oder dem OpenAI Python SDK http://127.0.0.1:5000/v1 als Basis-URL und den Wert aus --api-key als API-Key ein. Bestehende Skripte laufen so ohne Code-Änderung mit einem lokalen Modell.

Wie viel Speicherplatz brauche ich?

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

Fazit

text-generation-webui eignet sich, wenn Sie lokale LLMs mit vielen Formaten und Backends betreiben wollen. Der Docker-Weg erfordert einmalig einen längeren Build und trennt Image und Daten sauber: user_data/ hält Modelle und Einstellungen, CMD_FLAGS.txt die Startoptionen. Mit aktivierter API und API-Key nutzen bestehende OpenAI-Tools das lokale Modell, ohne Daten an Cloud-Dienste zu geben.

Alternativen: Ollama mit Open WebUI ist der einfachere Einstieg, vLLM für offene LLMs zielt auf hohen Durchsatz im Produktivbetrieb. Einen weiteren OpenAI-kompatiblen Server beschreibt LocalAI als OpenAI-kompatibler KI-Server.

Weiterführende Anleitungen und Quellen

  1. Ollama und Open WebUI mit Docker: eigenes lokales KI-Sprachmodell ohne Cloud betreiben
  2. Offene LLMs selbst serven mit vLLM (Llama, Mistral, Hermes)
  3. LocalAI mit Docker: lokaler, OpenAI-kompatibler KI-Server
  4. Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage
  5. 3-2-1-Backup-Strategie umsetzen: Anleitung mit Restic, USB-Disk und S3-Cloud

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