Paperless-ngx auf 3.0 updaten: Schritt-für-Schritt-Anleitung

Du betreibst Paperless-ngx selbst mit Docker? Dann betrifft dich das hier direkt: Seit dem 22. Juli 2026 ist Paperless-ngx 3.0 das offizielle Stable-Release, und das Docker-Tag :latest zeigt bereits darauf. Dein nächstes routinemäßiges docker compose pull holt also kein kleines Patch-Update mehr, sondern einen Major-Sprung mit Breaking Changes. Mit etwas Vorbereitung ist das kein Drama – diese Anleitung geht das Update Schritt für Schritt durch. Was die 3.0 inhaltlich bringt, haben wir im Feature-Überblick zu Paperless-ngx 3.0 beschrieben. Und falls du Paperless-ngx managed bei server.camp nutzt: Für dich ist hier nichts zu tun, das Update übernehmen wir.

Das Wichtigste in Kürze

• Nur von 2.20.15 aus: Das Upgrade auf 3.0 ist offiziell nur von Version 2.20.15 unterstützt. Ältere Installationen aktualisierst du zuerst nach 2.20.15.
• Backup zuerst: Datenbank, media/, data/ und die Konfiguration sichern – die Datenbank-Migrationen der 3.0 lassen sich nicht rückgängig machen, das Backup ist dein einziger Weg zurück.
• PAPERLESS_SECRET_KEY ist jetzt Pflicht, und wer PostgreSQL oder MariaDB nutzt, muss PAPERLESS_DBENGINE explizit setzen.
• Alte Variablen umziehen: OCR_MODE=skip, die CONSUMER_POLLING_*-Familie und einige weitere Einstellungen heißen anders oder sind weggefallen.
• Der Suchindex baut sich automatisch neu auf – beim ersten Start, ohne dein Zutun, je nach Archivgröße dauert das eine Weile.

Vor dem Update: Voraussetzungen prüfen

Drei Dinge klärst du am besten, bevor du irgendetwas anfasst:

• Läuft bei dir 2.20.15? Die Versionsnummer zeigt dir die Weboberfläche unten in der Seitenleiste. Der offizielle Migrationsleitfaden unterstützt das Upgrade auf 3.0 nur von 2.20.15 aus – ältere Installationen bringst du erst auf diesen Stand.
• Nutzt du noch die alte Dokumenten-Verschlüsselung? Das seit Jahren als veraltet markierte Feature wurde entfernt. Falls ja (das betrifft nur sehr alte Setups), entschlüsselst du vor dem Update mit dem Verwaltungsbefehl decrypt_documents.
• Ruhiges Zeitfenster wählen: Während des Updates sollte niemand scannen oder Dokumente hochladen. Der Consume-Ordner sollte leer sein.

Randnotiz für Bare-Metal-Installationen: Paperless-ngx 3.0 braucht mindestens Python 3.11. Docker-Nutzer:innen betrifft das nicht, das Image bringt alles mit.

Schritt 1: Backup – dein Rollback-Plan

Beim Start der 3.0 laufen Datenbank-Migrationen, die sich nicht rückgängig machen lassen. Wenn du danach zur 2.20.15 zurück willst, geht das nur über die Sicherung von vorher. Dazu gehören:

• die Datenbank – bei PostgreSQL z.B. per pg_dump, bei SQLite die Datei in data/,
• die Verzeichnisse media/ (deine Dokumente) und data/,
• docker-compose.yml und .env – damit du auch die alte Konfiguration wiederherstellen kannst.

Ergänzend lohnt ein Export über den eingebauten document_exporter, der Dokumente samt Metadaten in ein portables Format schreibt. Wie viel Betriebsaufwand solche Routinen auf Dauer bedeuten, haben wir im Vergleich Paperless-ngx Self-Hosted vs. Managed Hosting durchgerechnet.

Schritt 2: Konfiguration gegen die Breaking Changes abgleichen

Jetzt kommt der Teil, der das Major-Update vom Patch-Update unterscheidet: einmal mit der .env-Datei (bzw. dem environment:-Block der Compose-Datei) durch diese Checkliste. Die Hintergründe zu den einzelnen Änderungen stehen im Feature-Überblick.

Wichtig: Die 3.0 weist Duplikate beim Import nicht mehr automatisch ab, sondern nimmt sie an und markiert sie in der Weboberfläche. Wenn du das alte Verhalten willst, setzt du PAPERLESS_CONSUMER_DELETE_DUPLICATES=true.

Schritt 3: Update einspielen

Das eigentliche Update ist danach Routine:

cd /pfad/zu/paperless
docker compose down
docker compose pull
docker compose up -d
docker compose logs -f webserver

Wer im Compose-File eine feste Version gepinnt hat, ändert das Tag vorher auf 3.0.0. Beim ersten Start laufen die Datenbank-Migrationen automatisch durch – in den Logs siehst du den Fortschritt. Taucht dort eine Warnung über noch gesetzte alte Umgebungsvariablen auf, ist in Schritt 2 etwas durchgerutscht.

Schritt 4: Funktionscheck

Beim ersten Start baut Paperless-ngx den Suchindex automatisch neu auf – die alte Whoosh-Suche und das neue Tantivy-Backend sind nicht kompatibel. Im Docker-Image passiert das als Teil des Container-Starts (im Log als init-index sichtbar), noch bevor die Weboberfläche erreichbar ist. Keine Sorge wegen der Dauer: Tantivy indexiert schnell, ein Archiv mit ein paar hundert Dokumenten ist in Sekunden durch. Nur bei sehr großen Archiven verlängert der Schritt den ersten Start spürbar – dann lieber in die Logs schauen, statt den Start abzubrechen. Sobald du dich anmelden kannst, ein kurzer Rundgang:

• Anmelden und suchen: Findet die Volltextsuche bekannte Dokumente?
• Testdokument einwerfen: Landet eine PDF aus dem Consume-Ordner wie gewohnt mit OCR und Tags im Archiv?
• Gespeicherte Ansichten prüfen: Filter mit note: oder custom_field: werden automatisch auf die neue Syntax (notes.note:, custom_fields.value:) umgeschrieben. Nur unqualifizierte Suchbegriffe, die bisher zufällig Notizen mittrafen, musst du selbst ergänzen.
• OCR-Einstellungen ansehen: Hattest du OCR-Optionen über die Verwaltungsoberfläche gesetzt, migriert die 3.0 die Werte automatisch – ein Kontrollblick schadet trotzdem nicht.
• Leere Aufgabenliste nicht wundern: Die Task-Historie wird beim Upgrade geleert, das ist so vorgesehen.

Wenn etwas schiefgeht

Die häufigsten Stolperstellen haben bekannte Ursachen:

• 403-Fehler beim Login hinter einem Reverse Proxy: Die Login-Ratenbegrenzung ermittelt die Client-IP anders als bisher. Abhilfe schaffen PAPERLESS_TRUSTED_PROXIES und/oder PAPERLESS_ALLAUTH_TRUSTED_CLIENT_IP_HEADER.
• SSO-Login schlägt mit invalid_client fehl: OpenID-Connect-Setups brauchen unter Umständen ein explizites token_auth_method (z.B. client_secret_basic) in den Provider-Einstellungen.
• Gar nichts geht mehr: Container stoppen, Backup zurückspielen (Datenbank plus Verzeichnisse), Image-Tag auf 2.20.15 pinnen, starten – und das Update in Ruhe neu angehen. Genau dafür war Schritt 1 da.

Häufige Fragen zum Update auf Paperless-ngx 3.0

Kann ich direkt von 2.19 oder älter auf 3.0 springen? Nein. Der offizielle Weg führt über 2.20.15 – erst auf diese Version aktualisieren, dann auf 3.0. Der Zwischenschritt stellt sicher, dass alle älteren Datenbank-Migrationen sauber durchgelaufen sind.

Wie lange dauert das Update? Das Einspielen selbst ist in wenigen Minuten erledigt. Der automatische Neuaufbau des Suchindex beim ersten Start fällt bei typischen Archiven kaum ins Gewicht: In unserem Test war eine Instanz mit rund 400 Dokumenten in wenigen Sekunden fertig indexiert. Erst bei zehntausenden Dokumenten wird daraus eine nennenswerte Wartezeit – erreichbar ist die Weboberfläche jeweils erst danach.

Muss ich den Suchindex von Hand neu aufbauen? Nein, der Neuaufbau startet beim ersten Start automatisch. Nur wenn die Suche danach dauerhaft lückenhaft bleibt, lohnt ein manueller Anstoß per document_index reindex.

Was ist mit meinen Workflows, Tags und Korrespondenten? Die bleiben unverändert erhalten – die Breaking Changes betreffen Konfiguration und Schnittstellen, nicht deine Daten. Ein Backup brauchst du trotzdem, siehe Schritt 1.

Fazit

Das Update auf Paperless-ngx 3.0 ist gut beherrschbar, wenn die Reihenfolge stimmt: erst die Voraussetzungen klären, dann sichern, dann die Konfiguration gegen die Checkliste abgleichen – und erst danach docker compose pull. Die meisten Stolperstellen stecken in den umbenannten Umgebungsvariablen und den zwei neuen Pflichtangaben PAPERLESS_SECRET_KEY und PAPERLESS_DBENGINE; wer die vorab erledigt, erlebt einen unspektakulären Neustart mit anschließendem Index-Neuaufbau.

Belohnt wirst du mit der spürbar schnelleren Tantivy-Suche, Dokumentversionen und den weiteren Neuerungen aus unserem Feature-Überblick. Und falls du beim Durcharbeiten der Checkliste gemerkt hast, dass du solche Upgrades lieber nicht mehr selbst machen willst: Genau dieser Handgriff ist bei einem managed Paperless-ngx Teil des Pakets.