Paperless-ngx 3.0 upgraden: Migration ohne Datenverlust

Paperless-ngx 3.0 ist keine stille Wartungsversion — es ist ein echter Major-Release mit mehreren harten Breaking Changes. Wer einfach den Image-Tag tauscht und den Container neu startet, riskiert entweder einen Startfehler oder, im schlimmsten Fall, Inkonsistenzen in der Datenbank. Dieser Beitrag begleitet Sie durch das gesamte Upgrade von 2.x auf die aktuelle stabile Version 3.1.2: was sich ändert, was Sie vor dem ersten docker compose up erledigen müssen, und welche Fehler in der Community tatsächlich aufgetreten sind — inklusive Ursache und Lösung.

Was 3.0 konkret mit Ihrer Installation macht

Version 3.0.0 erschien am 22. Juli 2026; stabilisiert wurde die Reihe mit 3.0.5 am 1. August 2026. Die derzeit empfohlene Version ist 3.1.2 (erschienen 1. September 2026), die einen Security-Fix enthält. Wer bislang :latest gefahren ist und darauf vertraut hat, dass der Tag stabil bleibt, sollte ab jetzt auf einen festen Tag wechseln — dazu weiter unten mehr.

Breaking Changes im Überblick

Nicht jede Änderung betrifft jeden Betrieb, aber keine davon ist optional.

Änderung	Betrifft Sie, wenn …	Erforderliche Aktion
REST-API v1 entfernt	Drittanbieter-Apps oder Skripte nutzen /api/ ohne Versionsangabe oder v1-Endpunkte	Auf v2-Endpunkte umstellen
PAPERLESS_PASSPHRASE entfernt	Sie haben Dokumente verschlüsselt abgelegt	decrypt_documents vor dem Upgrade ausführen
PAPERLESS_DBENGINE jetzt Pflichtfeld	Jeder PostgreSQL- oder MariaDB-Betrieb	Variable in der Compose-Datei ergänzen
PAPERLESS_SECRET_KEY = 'change-me' abgelehnt	Wer den Standardwert nie geändert hat	Eigenen Zufallswert setzen
Python 3.10 weggefallen	Bare-Metal-Installationen auf Python 3.10	Docker-Nutzer nicht betroffen
Suchbackend: Whoosh → Tantivy	Alle Installationen	Reindex läuft automatisch beim ersten Start
Consume-Skripte ohne Positionsargumente	Eigene Pre/Post-Consumer-Skripte	Auf Umgebungsvariablen umstellen

Warum Tantivy statt Whoosh?

Das alte Whoosh-Suchbackend war rein Python-seitig implementiert — langsam bei großen Sammlungen, speicherhungrig, und die letzte aktive Entwicklung von Whoosh liegt Jahre zurück. Tantivy ist eine moderne Rust-Bibliothek, die heute in einer Reihe von Suchprojekten steckt. Für die Entscheidung, Whoosh vollständig herauszureißen statt ein Kompatibilitäts-Shim zu bauen, spricht ein konkreter Messwert aus dem offiziellen Pull-Request-Diskussionsfaden: Bei 9.000 Suchabfragen sank die Gesamtdauer von rund 1,5 Minuten (Whoosh) auf rund 30 Sekunden (Tantivy) — eine Fünffachbeschleunigung. Der Index auf Disk ist außerdem rund 40 Prozent kleiner. Bei kleinen Sammlungen unter 3.000 Dokumenten ist der Latenzvorteil im Alltag kaum spürbar, doch der Indexaufbau geht zwei- bis dreimal schneller durch.

Vor dem Upgrade: zwei Pflicht-Schritte

Verschlüsselte Dokumente zuerst entschlüsseln

Falls Sie PAPERLESS_PASSPHRASE gesetzt haben, entschlüsseln Sie Ihre Dokumente vor dem Image-Wechsel. Paperless-ngx 3.x verweigert den Start, wenn der Passphrase-Key noch in der Umgebung gesetzt ist.

# Laufender 2.x-Container — Verschluesselung aufheben:
docker compose exec paperless decrypt_documents

Lassen Sie den Befehl vollständig durchlaufen und entfernen Sie anschließend PAPERLESS_PASSPHRASE aus Ihrer .env-Datei. Die Dokumenten-Verschlüsselung ist in v3 ersatzlos entfallen. Wer Vertraulichkeit auf Storage-Ebene benötigt, setzt stattdessen auf LUKS oder verschlüsselte Objektspeicher-Buckets.

Backup — was, wohin, wie

Die Datenbank-Migration von 3.0 ist nicht rückwärtskompatibel: Einmal hochgezogen, können Sie nicht mehr auf 2.x zurück. Sichern Sie deshalb den PostgreSQL-Dump und die Verzeichnisse, bevor Sie fortfahren:

# PostgreSQL-Dump (laufender Stack):
docker compose exec db pg_dump -U paperless paperless > backup_$(date +%F).sql

# Media-Verzeichnis und Data-Verzeichnis:
tar czf paperless_media_$(date +%F).tar.gz ./media/ ./data/

Testen Sie die Wiederherstellung des Dumps mindestens einmal in einer Testumgebung. Wie im Beitrag zur 3-2-1-Backup-Strategie gilt: Ein Backup, das Sie nie zurückgespielt haben, ist kein Backup.

Das Upgrade mit Docker Compose

Die aktualisierte compose.yaml

Die drei kritischen Ergänzungen gegenüber einer typischen 2.x-Datei sind in Kommentaren kenntlich gemacht:

# compose.yaml fuer paperless-ngx 3.x
services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:3.1.2
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    ports:
      - "8000:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://redis:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql          # NEU in v3: Pflichtfeld
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: ${DB_PASS}
      PAPERLESS_SECRET_KEY: ${SECRET_KEY}    # Kein 'change-me' erlaubt
      PAPERLESS_TIME_ZONE: Europe/Berlin
      PAPERLESS_OCR_LANGUAGE: deu+eng
      PAPERLESS_URL: https://dokumente.beispiel.de

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${DB_PASS}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperless"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

volumes:
  pgdata:
  redisdata:

Warum hier der feste Tag 3.1.2 statt :latest? Der :latest-Tag zeigt zuverlässig auf den letzten stabilen Release. Trotzdem empfehle ich den festen Tag: Ein unerwartetes Major-Update bei docker compose pull kann exakt die Breaking-Change-Situation auslösen, aus der Sie gerade heraus wollen. Ein expliziter Tag zwingt Sie zum bewussten Upgrade-Entscheid und macht nachvollziehbar, auf welchem Stand Ihre Instanz läuft.

Wie Sie den Container hinter einem Reverse Proxy betreiben, damit Port 8000 nicht direkt exponiert ist, beschreibt nginx als Reverse Proxy im Container. Den Healthcheck-Ansatz für komplexere Multi-Service-Stacks erklärt Docker Compose: Multi-Service-Setup mit Healthchecks.

Starten, beobachten, prüfen

docker compose pull
docker compose up -d
docker compose logs -f paperless

Beim ersten Start sehen Sie die Datenbank-Migrationen durchlaufen, gefolgt vom Tantivy-Reindex. Bei einer Sammlung von rund 5.000 Dokumenten auf einem moderaten Server (4 vCPUs, SSD) dauerte der Reindex in unserer Umgebung etwa 7 Minuten. Danach ist die Web-UI vollständig zugänglich.

Tantivy im laufenden Betrieb: was sich wirklich ändert

Die Suche reagiert spürbar schneller, vor allem bei längeren Suchbegriffen oder Fuzzy-Suchen (Tilde-Operator ~1 am Wortende). Tantivy liefert außerdem Highlighting: Treffer werden im Volltext-Preview hervorgehoben, was Fehlklassifizierungen früher auffallen lässt.

Kriterium	Whoosh (bis 2.x)	Tantivy (ab 3.0)
Implementierung	Python	Rust
Indexaufbau bei 25.000 Dokumenten	~45 Minuten	~15 Minuten
9.000 Suchabfragen gesamt	~1,5 Minuten	~30 Sekunden
Index-Größe auf Disk	Referenz	~40 % kleiner
Fuzzy-Suche / Highlighting	rudimentär	nativ
Bare-Metal-Reindex-Befehl	document_index reindex	identisch

Für deutschsprachige Betriebe ist die einzig relevante Einschränkung: Sehr ungewöhnliche Sonderzeichen oder CJK-Zeichen ohne OCR sollten vor dem Live-Upgrade in einer Testinstanz auf korrekte Tokenisierung geprüft werden. Im normalen Bürobetrieb ist das kein Thema.

Zwei Fehler, die tatsächlich aufgetreten sind

Startup-Fehler: PAPERLESS_DBENGINE fehlt

Das ist der bei weitem häufigste Fehler nach dem Image-Wechsel:

django.core.exceptions.ImproperlyConfigured:
  'PAPERLESS_DBENGINE' must be set explicitly.
  Supported values: postgresql, mariadb

Ursache: In v2 leitete Paperless-ngx die Datenbank-Engine implizit aus dem Vorhandensein von PAPERLESS_DBHOST ab — gesetzt bedeutete PostgreSQL. Das war fehleranfällig. In v3 ist das Feld Pflicht. Lösung: PAPERLESS_DBENGINE: postgresql (oder mariadb) in die Compose-Datei eintragen und den Container neu starten.

Migrations-Kollision in 3.0.1 (betrifft nur Frühinstaller)

Wer zwischen dem 22. und 28. Juli 2026 auf genau 3.0.0 oder 3.0.1 aktualisiert hat, konnte folgende Fehlermeldung sehen:

django.db.migrations.exceptions.InconsistentMigrationHistory:
  Migration paperless_mail.0002_optimize_integer_field_sizes
  is applied before its dependency
  paperless_mail.0001_1_clamp_mailrule_maximum_age
  on database 'default'.

Ursache: Eine nachträglich eingefügte Migration für die paperless_mail-App kollidierte mit dem bereits angewendeten Migrations-Stand aus 3.0.0. Das war ein Fehler im Release-Prozess und wurde in 3.0.2 behoben. Wer direkt auf 3.0.2 oder höher upgradet, ist nicht betroffen. Wer auf 3.0.0 oder 3.0.1 feststeckt, kann direkt auf 3.1.2 ziehen — das Upgrade läuft dann sauber durch.

Häufige Fragen

Muss ich zwingend auf 2.20.15 sein, bevor ich auf 3.x upgrade? Ja. Der direkte Upgrade-Pfad setzt 2.20.15 als Startversion voraus. Wer älter ist, führt erst das Update auf 2.20.15 durch, bevor er auf 3.x wechselt.

Was passiert mit meinen Consume-Skripten? Pre- und Post-Consume-Skripte, die Positionsargumente verwenden (z. B. $1 für den Dateipfad), werden nicht mehr aufgerufen — Paperless-ngx 3.0 übergibt alle Informationen ausschließlich über Umgebungsvariablen wie DOCUMENT_ID und DOCUMENT_FILE_NAME. Passen Sie Ihre Skripte entsprechend an.

Gibt es eine Möglichkeit, Whoosh zu behalten? Nein. Whoosh wurde vollständig entfernt; es gibt keine Kompatibilitätsoption oder Konfigurationsflag.

Wie lange dauert der Tantivy-Reindex? Als grober Richtwert: 5.000 Dokumente auf einer SSD in 5–10 Minuten, 25.000 Dokumente in etwa 15 Minuten. Während des Reindex ist die Web-UI eingeschränkt nutzbar, aber erreichbar.

Ist das neue Plugin-Framework produktionsreif? Es ist vorhanden, aber offiziell als experimentell markiert. Für Produktionsinstallationen empfiehlt das Projekt, eigene Plugins gründlich in einer Testinstanz zu validieren, bevor sie live gehen.

Von der Dokumentenablage zur strukturierten Archivierung

Wer Paperless-ngx produktiv einsetzt, verwaltet häufig nicht nur eingescannte Belege, sondern auch ZUGFeRD- oder XRechnung-Dokumente. Was ab 2027 an regulatorischen Anforderungen auf Unternehmen zukommt, erläutert der Beitrag E-Rechnung: Pflicht ab 2027 — und warum eine GoBD-konforme Ablage in diesem Kontext mehr ist als eine gute Idee.

Offizielle Dokumentation: Paperless-ngx Migration Guide v3, Changelog, GitHub Releases.

Wenn Sie Unterstützung bei Einrichtung, Betrieb oder einer revisionssicheren Dokumentenablage benötigen, finden Sie weitere Informationen zu unserem IT-Support.