---
title: "text-generation-webui mit Docker installieren: Umfassende Web-UI für lokale LLMs (llama.cpp, ExLlama, Transformers)"
date: 2026-08-18T09:07:15+02:00
modified: 2026-11-08T22:07:54+01:00
category: kuenstliche-intelligenz
type: how_to
author: Marcel Schönfelder
canonical: https://s-edv.com/anleitungen/text-generation-webui-docker-llm-ui
reading_time: 9
personalize_url: "https://s-edv.com/anleitungen/text-generation-webui-docker-llm-ui#ip_1={ip_1}&host_port={host_port}"
variables:
  - name: ip_1
    label: "IP Adresse"
    default: "127.0.0.1"
  - name: host_port
    label: "Host port"
    default: "HOST_PORT"
  - name: ihr_api_key
    label: "Ihr api key"
    default: "IHR-API-KEY"
---

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

## Anpassbare Werte

Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`:

| Platzhalter | Bedeutung | Beispielwert |
| --- | --- | --- |
| `{{ip_1}}` | IP Adresse | `127.0.0.1` |
| `{{host_port}}` | Host port | `HOST_PORT` |
| `{{ihr_api_key}}` | Ihr api key | `IHR-API-KEY` |

Link mit eigenen Werten: https://s-edv.com/anleitungen/text-generation-webui-docker-llm-ui#ip_1=127.0.0.1&host_port=HOST_PORT

Dieser Link öffnet die Anleitung und schlägt dem Leser die Werte vor. Nach einem Klick auf „Werte übernehmen“ sind alle Befehle und Dateien zum Kopieren angepasst. Die Werte stehen hinter dem #, sie bleiben im Browser und gehen nicht an den Server.

*Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten und geben Sie ihm den Link mit diesen Werten, statt die Befehle selbst umzuschreiben.

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.

**Kurzfassung:** Sie klonen das offizielle Repository, passen in der `.env` die CUDA Compute Capability Ihrer GPU an, binden die Ports an `{{ip_1}}` und bauen das Image lokal mit `docker compose build`. Danach starten Sie mit `docker compose up -d`; die Web-UI ist unter `http://localhost:7860` erreichbar. Modelle laden Sie über den Tab „Model“ herunter. Ohne lokalen Build nutzen Sie das Community-Image `atinoda/text-generation-webui`. Die OpenAI-kompatible API auf Port 5000 aktivieren Sie mit `--api --api-key` in `CMD_FLAGS.txt`.

## 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](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage)
- [ ] **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](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten) 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.

```bash
# Repository klonen (einmalig)
```

```bash
$ git clone https://github.com/oobabooga/text-generation-webui.git
$ cd text-generation-webui
```

```bash
# Für NVIDIA-GPU:
```

```bash
$ cd docker/nvidia
```

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

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

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

```bash
$ mkdir -p user_data
```

```bash
# .env aus dem Beispiel erstellen
```

```bash
$ 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`.

> **Prüfen:** Die folgenden Dateien und Verzeichnisse sind vorhanden:
>
> ```bash
> $ ls -la
> ```
>
> ```bash
> # 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-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 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 `{{ip_1}}`, da die Web-UI keine Anmeldung hat:

```ini
# .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}}={{ip_1}}:7860
CONTAINER_PORT=7860
HOST_API_PORT={{ip_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=
```

> **Prüfen:** Die gesetzten Werte enthalten Ihren `TORCH_CUDA_ARCH_LIST`-Wert:
>
> ```bash
> $ grep -v '^#' .env | grep -v '^$'
> ```
>
> ```bash
> # 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.

```bash
# Im Verzeichnis docker/nvidia/ (oder amd/cpu/intel/)
```

```bash
$ docker compose build
```

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

> **Prüfen:** Nach dem erfolgreichen Build erscheint das Image in der lokalen Registry:
>
> ```bash
> $ docker images | grep textgen
> ```
>
> ```bash
> # 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:

| 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 `docker-compose.yml` für NVIDIA aus dem Repository; die Zeile `restart: unless-stopped` ergänzen Sie selbst, sie fehlt im Original:

```yaml
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:

```bash
$ docker compose up -d
```

> **Prüfen:** Container-Status und Logs zeigen einen laufenden Dienst:
>
> ```bash
> $ docker compose ps
> ```
>
> ```bash
> # Erwartete Ausgabe:
> # NAME        IMAGE          COMMAND   SERVICE   STATUS    PORTS
> # nvidia-textgen-1   nvidia-textgen   ...   textgen   Up   {{ip_1}}:7860->7860/tcp
> ```
>
> ```bash
> $ docker compose logs --tail=30
> ```
>
> ```bash
> # 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:{{ip_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.

> **Prüfen:** Die Web-UI antwortet, und im Chat-Tab liefert das geladene Modell eine Antwort:
>
> ```bash
> $ curl -I http://localhost:7860
> ```
>
> ```bash
> # 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:

```bash
# CMD_FLAGS.txt anlegen/bearbeiten
```

```bash
$ echo "--api --listen --api-key $(openssl rand -hex 24)" > user_data/CMD_FLAGS.txt
$ cat user_data/CMD_FLAGS.txt   # Schlüssel notieren
```

```bash
# Container neu starten damit die Flags wirken
```

```bash
$ docker compose restart
```

Die API ist anschließend unter `http://{{ip_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](https://s-edv.com/anleitungen/qdrant-rag-system-lokal-embeddings-anleitung).

> **Prüfen:** Die API antwortet mit dem Schlüssel (`{{ihr_api_key}}` ersetzen):
>
> ```bash
> 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:

```bash
# Ins Repository-Root-Verzeichnis wechseln
```

```bash
$ cd /pfad/zu/text-generation-webui
```

```bash
# Neue Version holen
```

```bash
$ git pull
```

```bash
# Zurück in den Varianten-Ordner und neu bauen
```

```bash
$ 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](https://s-edv.com/anleitungen/3-2-1-backup-strategie-praktisch-umsetzen) genügen, um alles zu sichern.

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

```bash
$ docker compose pull
$ docker compose up -d
```

> **Prüfen:** Der Container läuft nach dem Update wieder:
>
> ```bash
> $ docker compose ps
> ```
>
> ```bash
> # STATUS: Up (running)
> ```
>
> ```bash
> $ docker compose logs --tail=10
> ```
>
> ```bash
> # 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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) (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}}={{ip_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 `{{ip_1}}`:

```yaml
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:
      - "{{ip_1}}:7860:7860"
      - "{{ip_1}}:5000:5000"
      - "{{ip_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://{{ip_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](https://s-edv.com/anleitungen/ollama-open-webui-docker-lokales-llm) ist der einfachere Einstieg, [vLLM für offene LLMs](https://s-edv.com/anleitungen/offene-llms-vllm-selbst-hosten-docker) zielt auf hohen Durchsatz im Produktivbetrieb. Einen weiteren OpenAI-kompatiblen Server beschreibt [LocalAI als OpenAI-kompatibler KI-Server](https://s-edv.com/anleitungen/localai-openai-kompatibler-ki-server-docker).

## Weiterführende Anleitungen und Quellen

1. [Ollama und Open WebUI mit Docker: eigenes lokales KI-Sprachmodell ohne Cloud betreiben](https://s-edv.com/anleitungen/ollama-open-webui-docker-lokales-llm)
2. [Offene LLMs selbst serven mit vLLM (Llama, Mistral, Hermes)](https://s-edv.com/anleitungen/offene-llms-vllm-selbst-hosten-docker)
3. [LocalAI mit Docker: lokaler, OpenAI-kompatibler KI-Server](https://s-edv.com/anleitungen/localai-openai-kompatibler-ki-server-docker)
4. [Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage)
5. [3-2-1-Backup-Strategie umsetzen: Anleitung mit Restic, USB-Disk und S3-Cloud](https://s-edv.com/anleitungen/3-2-1-backup-strategie-praktisch-umsetzen)

Offizielle Dokumentation: [text-generation-webui GitHub Repository](https://github.com/oobabooga/text-generation-webui) | [Docker-Dokumentation (Ordner docs)](https://github.com/oobabooga/text-generation-webui/blob/main/docs/09%20-%20Docker.md) | [atinoda/text-generation-webui auf Docker Hub](https://hub.docker.com/r/atinoda/text-generation-webui)
