--- title: "LibreTranslate mit Docker: Übersetzungs-API selbst hosten" date: 2026-10-01T02:19:16+02:00 modified: 2026-11-10T17:40:38+01:00 category: docker type: how_to author: Marcel Schönfelder canonical: https://s-edv.com/anleitungen/libretranslate-docker-uebersetzungs-api-selbst-hosten keywords: - LibreTranslate - Docker - Übersetzung - Selfhosting - Datenschutz - API - Argos Translate reading_time: 10 --- # LibreTranslate mit Docker: Übersetzungs-API selbst hosten Wer Angebote, Support-Tickets oder interne Dokumente maschinell übersetzen lässt, schickt die Texte bei Cloud-Diensten zwangsläufig an einen fremden Server. LibreTranslate ist eine quelloffene Übersetzungs-API, die komplett auf eigener Hardware läuft und dafür die Open-Source-Bibliothek Argos Translate nutzt. Diese Anleitung zeigt Betrieb mit Docker Compose, Schlüsselpflicht, Persistenz sowie Backup und Restore. Alle Messwerte stammen aus Testläufen mit Version v1.9.6. **Kurzfassung:** LibreTranslate läuft als einzelner Container mit dem offiziellen Image `libretranslate/libretranslate`. Mit `LT_LOAD_ONLY=en,de` lädt der Dienst nur Deutsch und Englisch, das sind rund 315 MB Modelldaten in einem benannten Volume. Der Container braucht im Leerlauf etwa 250 MiB RAM und nach den ersten Übersetzungen rund 860 MiB. Mit `LT_API_KEYS=true` und `LT_REQ_LIMIT=0` lehnt die API jede Anfrage ohne gültigen Schlüssel mit HTTP 429 ab. Die Qualität reicht für Rohübersetzungen und interne Zwecke, erreicht aber nicht das Niveau von DeepL oder großen Sprachmodellen. ## Voraussetzungen LibreTranslate rechnet standardmäßig auf der CPU, eine Grafikkarte ist nicht nötig. Das optionale CUDA-Image ist rund 1,9 GB groß und nur für amd64 verfügbar. Für ein Sprachpaar wie Deutsch und Englisch reicht ein kleiner Server: - [ ] **CPU:** 2 Kerne genügen für einzelne Anfragen. Der Testhost hatte 2 Kerne, eine kurze Übersetzung mit zwei Sätzen dauerte dort zwischen 0,18 und 0,34 Sekunden. - [ ] **RAM:** 2 GB sind das Minimum, 4 GB geben Luft für mehrere Worker und weitere Sprachen. Gemessen wurden 251 MiB im Leerlauf und bis zu 863 MiB nach Text- und Dateiübersetzungen. - [ ] **Speicher:** etwa 850 MB für das entpackte Image (201 MB Download) plus rund 160 MB je Übersetzungsrichtung. Jede zusätzliche Sprache vergrößert das Modell-Volume deutlich. - [ ] **Architektur:** Das Image `v1.9.6` gibt es laut Docker Hub für amd64 und arm64. - [ ] **Software:** Docker Engine mit Compose-Plugin, ein Benutzer mit Docker-Rechten, für den Produktivbetrieb ein Reverse Proxy mit TLS. Die Installation beschreibt die Anleitung [Docker und Docker Compose auf Linux installieren](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage). ## Schritt 1: Projektstand prüfen und Version festlegen LibreTranslate wird auf GitHub unter `LibreTranslate/LibreTranslate` entwickelt und steht unter der AGPL-3.0. Das jüngste Release ist v1.9.6 vom 26.05.2026: Der Code wird aktiv gepflegt, versionierte Releases erscheinen in größeren Abständen. Auf Docker Hub gibt es neben den Versionstags auch `latest`, das nach dem Release neu gebaut wurde und damit nicht dem Release-Stand entspricht. Für einen nachvollziehbaren Betrieb schreiben Sie deshalb eine Version fest. Diese Anleitung nutzt `v1.9.6`. | Eckdatum | Wert | | --- | --- | | Image | `libretranslate/libretranslate:v1.9.6` | | Port im Container | `5000` (HTTP, Gunicorn) | | Volume Modelle | `/home/libretranslate/.local` | | Volume Schlüssel | `/app/db` mit `api_keys.db` (SQLite) | | Wichtige Variablen | `LT_LOAD_ONLY`, `LT_API_KEYS`, `LT_REQ_LIMIT`, `LT_CHAR_LIMIT` | | Benutzer im Container | UID 1032, GID 65534 | > **Prüfen:** `curl -sI https://github.com/LibreTranslate/LibreTranslate/releases/latest` leitet auf `/releases/tag/v1.9.6` weiter. Weicht der Tag ab, prüfen Sie die Release-Notes, bevor Sie die Version in der `.env` anpassen. ## Schritt 2: compose.yaml und .env anlegen Legen Sie einen Projektordner an, zum Beispiel `/opt/libretranslate`. Die Repository-Vorlage enthält Volumes und Schlüssel nur auskommentiert; diese Fassung aktiviert beides und bindet den Port an localhost. ```yaml services: libretranslate: image: libretranslate/libretranslate:${LT_VERSION} container_name: libretranslate restart: unless-stopped ports: # nur lokal erreichbar, der Reverse Proxy spricht diesen Port an - "127.0.0.1:${LT_HOST_PORT}:5000" env_file: .env healthcheck: test: ['CMD-SHELL', './venv/bin/python scripts/healthcheck.py'] interval: 10s timeout: 4s retries: 4 start_period: 120s volumes: # Sprachmodelle, verhindert erneuten Download bei jedem Start - lt_models:/home/libretranslate/.local:rw # SQLite-Datenbank mit den API-Schlüsseln - lt_db:/app/db volumes: lt_models: lt_db: ``` Die Variablen stammen aus der offiziellen Argumentliste: Jeder Startparameter hat eine Entsprechung mit Präfix `LT_` in Großbuchstaben, aus `--char-limit` wird also `LT_CHAR_LIMIT`. Zur Härtung der Compose-Datei mit Secrets, Healthchecks und Non-Root siehe [Docker Compose absichern](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root). ```ini # Version festschreiben, nicht latest LT_VERSION=v1.9.6 LT_HOST_PORT=18750 # nur Deutsch und Englisch laden LT_LOAD_ONLY=en,de # Schlüsseldatenbank aktivieren und Pfad im Volume festlegen LT_API_KEYS=true LT_API_KEYS_DB_PATH=/app/db/api_keys.db # 0 Anfragen pro Minute ohne Schlüssel: Schlüssel wird Pflicht LT_REQ_LIMIT=0 # maximale Zeichen pro Anfrage LT_CHAR_LIMIT=5000 # optional, wenn nur die API gebraucht wird # LT_DISABLE_WEB_UI=true ``` Die `.env` enthält keine Geheimnisse, die Schlüssel selbst liegen später in der Datenbank. Die Kombination aus `LT_REQ_LIMIT=0` und `LT_API_KEYS=true` empfiehlt die Dokumentation ausdrücklich, um die API nur noch mit gültigem Schlüssel nutzbar zu machen. > **Prüfen:** `docker compose config` zeigt die aufgelöste Datei mit `v1.9.6` und `127.0.0.1:18750` ohne Fehlermeldung. ## Schritt 3: Container starten und Modelle laden ```bash $ cd /opt/libretranslate $ docker compose pull $ docker compose up -d $ docker compose logs -f --no-log-prefix ``` Beim ersten Start lädt der Container die Modellliste, behält wegen `LT_LOAD_ONLY` nur zwei der 100 gefundenen Modelle und lädt `English → German (1.3)` und `German → English (1.3)` herunter. Die Meldung `Loaded support for 2 languages (2 models total)!` erscheint nach rund 15 Sekunden im Log, danach startet Gunicorn auf Port 5000. Das Modell-Volume belegte anschließend 316 MB. > **Prüfen:** `docker compose ps` zeigt `healthy`, und `curl -s http://127.0.0.1:18750/languages` liefert genau zwei Einträge, `en` und `de`. ## Schritt 4: API-Schlüssel anlegen und Pflicht prüfen Schlüssel verwalten Sie mit dem Werkzeug `ltmanage` im Container. Die Zahl gibt die erlaubten Anfragen pro Minute an, `--char-limit` optional eine eigene Zeichengrenze je Schlüssel. Geben Sie den Datenbankpfad immer mit an, damit Werkzeug und Dienst dieselbe Datei verwenden. ```bash # Schlüssel mit 60 Anfragen pro Minute anlegen docker compose exec libretranslate ./venv/bin/ltmanage keys \ --api-keys-db-path /app/db/api_keys.db add 60 --char-limit 5000 # vorhandene Schlüssel anzeigen docker compose exec libretranslate ./venv/bin/ltmanage keys \ --api-keys-db-path /app/db/api_keys.db ``` Der Befehl gibt eine UUID aus, das ist der Schlüssel. Geben Sie jedem Werkzeug einen eigenen Schlüssel, dann sperren Sie ihn gezielt mit `remove `. Der Negativtest gehört dazu: Ohne Schlüssel und mit einem erfundenen Schlüssel antwortet die API jeweils mit `HTTP 429` und `{"error":"Slowdown: 0 per 1 minute"}`. Skripte, die nur auf 401 prüfen, erkennen einen falschen Schlüssel deshalb nicht. > **Prüfen:** Eine Anfrage ohne `api_key` liefert 429, dieselbe Anfrage mit gültigem Schlüssel liefert 200. ## Schritt 5: Texte und Dateien übersetzen Die API nimmt JSON oder Formulardaten entgegen. Für eine Übersetzung von Deutsch nach Englisch genügt ein POST auf `/translate`: ```bash curl -s -X POST http://127.0.0.1:18750/translate \ -H 'Content-Type: application/json' \ -d '{"q":"Die Rechnung ist bis Ende des Monats zu bezahlen. Bitte senden Sie uns die unterschriebene Vereinbarung zurück.","source":"de","target":"en","api_key":"IHR-SCHLÜSSEL"}' ``` Ergebnis: `The bill must be paid by the end of the month. Please return the signed agreement to us.` Mit `"source":"auto"` erkennt LibreTranslate die Ausgangssprache selbst und meldet sie mit einer Konfidenz zurück, zum Beispiel 43 für einen kurzen deutschen Satz. HTML bleibt mit `"format":"html"` erhalten. Dateien nimmt der Endpunkt `/translate_file` als Multipart-Upload an und gibt eine Download-URL zurück. Für Python, PHP, Go und weitere Sprachen nennt die Dokumentation fertige Client-Bibliotheken. Sprachen, die nicht geladen sind, lehnt der Dienst sauber ab: Eine Anfrage nach Französisch ergab `HTTP 400` mit `fr is not supported`. 6.000 Zeichen scheiterten mit `exceeds text limit (5000)`. > **Prüfen:** Die Antwort enthält das Feld `translatedText`, und `docker stats --no-stream libretranslate` zeigt die RAM-Belegung unter Last. Es sind rund 860 MiB. ## Schritt 6: Persistenz der Modelle prüfen Ohne Modell-Volume lädt LibreTranslate bei jedem neu erstellten Container alle Modelle erneut herunter. Prüfen Sie deshalb einmal bewusst den kompletten Neuaufbau: ```bash $ docker compose down $ docker compose up -d $ docker compose logs --no-log-prefix | grep -E 'Download|Loaded' ``` Nach dem Neuaufbau erscheint keine einzige `Downloading`-Zeile mehr, der Container ist nach rund sechs Sekunden `healthy`, und der zuvor angelegte Schlüssel funktioniert weiter. > **Prüfen:** Die Log-Abfrage liefert keine Download-Zeilen, und eine Übersetzung mit dem alten Schlüssel ergibt HTTP 200. ## Schritt 7: Reverse Proxy und TLS Der Container spricht nur HTTP und lauscht auf localhost. Für den Zugriff aus dem Netz setzen Sie einen Reverse Proxy mit automatischem Zertifikat davor, etwa Caddy oder Traefik, und leiten eine Subdomain auf `127.0.0.1:18750` weiter. Geben Sie den Dienst möglichst nur intern oder per VPN frei. Nutzen Sie nur die API, schalten Sie die Weboberfläche mit `LT_DISABLE_WEB_UI=true` ab; die Startseite liefert sonst HTTP 200. > **Prüfen:** `curl -I https://translate.example.de/languages` liefert HTTP 200 mit gültigem Zertifikat, und von außen ist Port 18750 nicht erreichbar. ## Schritt 8: Backup und Restore der Schlüsseldatenbank Die Modelle lassen sich jederzeit neu laden, die Schlüsseldatenbank nicht. Sichern Sie daher das Volume `lt_db`, idealerweise bei gestopptem Container, damit SQLite nicht mitten im Schreiben kopiert wird. Compose stellt den Projektnamen voran, hier `libretranslate_lt_db`. ```bash mkdir -p backup docker compose stop docker run --rm -v libretranslate_lt_db:/data:ro -v "$PWD/backup":/backup \ alpine tar czf /backup/lt_db.tar.gz -C /data . docker compose start ``` Für den Restore stoppen Sie den Dienst, ersetzen die Datei und starten neu. Das Archiv bewahrt die Eigentümer UID 1032 und GID 65534, der Dienst kann die Datei danach wieder schreiben. ```bash docker compose stop docker run --rm -v libretranslate_lt_db:/data -v "$PWD/backup":/backup:ro \ alpine sh -c 'rm -f /data/api_keys.db && tar xzf /backup/lt_db.tar.gz -C /data' docker compose start ``` Der Schlüssel wurde nach der Sicherung mit `ltmanage keys remove` gelöscht. Die Liste meldete danach `There are no API keys`, und Anfragen mit dem Schlüssel scheiterten mit 429. Nach dem Restore war der Schlüssel samt Limit 60 wieder gelistet, die Übersetzung lieferte erneut HTTP 200. > **Prüfen:** `ltmanage keys` listet den gesicherten Schlüssel wieder, und eine Übersetzung damit ergibt HTTP 200. ## Schritt 9: Updates und Rollback Für ein Update tragen Sie den neuen Tag in die `.env` ein, sichern vorher `lt_db` und führen `docker compose pull` sowie `docker compose up -d` aus. Neue Modellversionen holt `LT_UPDATE_MODELS=true` beim Start; sie lädt laut Dokumentation immer neu, daher nur für den Update-Lauf setzen. Ein Rollback bedeutet, den alten Tag zurückzuschreiben und neu zu starten. Ob ältere Versionen eine neuere Schlüsseldatenbank lesen, ist nicht dokumentiert; spielen Sie daher auch die Sicherung zurück. > **Prüfen:** Die erste Logzeile nach dem Banner zeigt die neue Versionsnummer, `docker compose ps` meldet `healthy`. ## Schritt 10: LibreTranslate entfernen Zum vollständigen Entfernen dient `docker compose down -v`. **Achtung:** Die Option `-v` löscht beide Volumes und damit unwiderruflich alle API-Schlüssel. Sichern Sie vorher das Volume `lt_db`, falls Sie die Schlüssel noch brauchen. Das Image entfernen Sie anschließend mit `docker rmi libretranslate/libretranslate:v1.9.6`. > **Prüfen:** `docker volume ls --filter name=libretranslate` liefert keine Einträge mehr, und `docker ps -a` zeigt keinen Container `libretranslate`. ## Troubleshooting **HTTP 429 trotz Schlüssel** Schlüssel falsch kopiert, gesperrt oder in einer anderen Datenbank angelegt. Prüfen Sie mit `ltmanage keys --api-keys-db-path /app/db/api_keys.db`, ob er gelistet ist. Ohne Volume auf `/app/db` gehen Schlüssel beim Neuaufbau verloren. **Container-Name belegt** Ein zweiter Stack mit derselben Datei scheitert mit `Conflict. The container name "/libretranslate" is already in use`. Entfernen Sie `container_name` oder vergeben Sie einen eindeutigen Namen. **Sprache fehlt** `xx is not supported` bedeutet, dass das Modell nicht geladen ist. Ein ungültiger Code in `LT_LOAD_ONLY` führt zu keiner Fehlermeldung, der Dienst startet normal; kontrollieren Sie nach jeder Änderung `/languages`. **Text zu lang** `exceeds text limit` zeigt die Zeichengrenze. Teilen Sie lange Dokumente auf oder erhöhen Sie das Limit gezielt pro Schlüssel. ## Häufige Fragen ### Wie gut ist die Übersetzungsqualität? Für einfache Geschäftssätze ordentlich, für Marketingtexte oder Verträge ohne Nachbearbeitung zu ungenau. Beispielsweise wurde aus „Guten Tag“ brauchbar „Good afternoon“, aus „Guten Morgen“ in einem HTML-Absatz aber „Goodies morning“. DeepL oder große Sprachmodelle liefern meist flüssigere Texte, auf Kosten von Datenweitergabe oder Hardware. ### Werden Texte an externe Server gesendet? Nein, die Übersetzung läuft lokal. Nur beim ersten Start lädt der Container Modellindex und Modelle aus dem Internet. ### Wie viele Sprachen sollte ich laden? Nur die benötigten. Jede Sprache erhöht Speicher, Startzeit und RAM; meist reichen Deutsch und Englisch. ### Darf ich LibreTranslate im Unternehmen einsetzen? Ja, die Software steht unter der AGPL-3.0. Bieten Sie eine veränderte Version als Netzdienst für Dritte an, müssen Sie deren Quellcode bereitstellen. Für den Namen und das Logo gelten zusätzlich die Markenrichtlinien des Projekts. ## Fazit Mit zwei Sprachen genügt ein kleiner Server, und das Backup beschränkt sich auf eine SQLite-Datei. Die Grenzen liegen bei der Qualität und bei der Rückmeldung der API: Ein falscher Schlüssel ergibt 429 statt 401, und ungültige Sprachcodes fallen erst bei `/languages` auf. Für Rohübersetzungen, interne Dokumente und die Anbindung eigener Werkzeuge ist LibreTranslate eine gute Wahl, für veröffentlichte Texte bleibt menschliches Gegenlesen Pflicht. ## Weiterführende Anleitungen und Quellen - [Caddy als Reverse Proxy mit automatischem HTTPS](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung) - [Traefik als Docker-Reverse-Proxy mit HTTPS einrichten](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten) - [Ollama und Open WebUI: lokales Sprachmodell als Alternative für anspruchsvollere Texte](https://s-edv.com/anleitungen/ollama-open-webui-docker-lokales-llm) - [Paperless-ngx: Dokumentenverwaltung mit OCR im eigenen Netz](https://s-edv.com/anleitungen/paperless-ngx-dokumentenverwaltung-ocr-docker) - [LibreTranslate auf GitHub](https://github.com/LibreTranslate/LibreTranslate) - [Offizielle Dokumentation: Installation und Argumente](https://docs.libretranslate.com/guides/installation/) - [Offizielle Dokumentation: API-Nutzung](https://docs.libretranslate.com/guides/api_usage/) - [Offizielle Dokumentation: API-Schlüssel verwalten](https://docs.libretranslate.com/guides/manage_api_keys/) - [Image-Tags auf Docker Hub](https://hub.docker.com/r/libretranslate/libretranslate/tags) - [Argos Translate, die zugrunde liegende Übersetzungsbibliothek](https://github.com/argosopentech/argos-translate)