pad.systems
Kontakt

Blog · Software · Ratgeber

Paperless-ngx 3 ist stabil: was neu ist und wie Sie updaten

Paperless-ngx 3 ist seit Juli stabil, aktuell ist 3.4.1. Was aus der Beta wurde, was 3.1 bis 3.4 nachgelegt haben und was das Update von 2.x verlangt.

pad systems 7 Min. Lesezeit

Strichzeichnung: Der Igel liest im Aktenarchiv, der Roboter hilft am Regal

Paperless-ngx 3.0.0 erschien am 22. Juli 2026. Bis Ende Oktober folgten achtzehn weitere Releases, aktuell ist 3.4.1 vom 31. Oktober (Releases auf GitHub). Die Beta ist damit vorbei, die ersten Kinderkrankheiten sind behoben. Für die meisten Installationen ist jetzt ein guter Zeitpunkt für das Update.

Ein Klick ist es trotzdem nicht. Version 3 ändert Umgebungsvariablen, die Suchsyntax und die Schnittstelle zu eigenen Skripten. Wer einfach das neue Image zieht, merkt das spätestens beim ersten Start. Dieser Artikel ergänzt unsere Übersicht zur Beta um den stabilen Stand und beschreibt das Update so, wie wir es bei Kunden durchführen.

Was aus der Beta wurde

Die großen Neuerungen der ersten Beta vom Mai sind alle im Stable angekommen: die Suche auf Basis von Tantivy statt Whoosh, die Dokument-Versionierung, das Plugin-Framework für Dokument-Parser, das neue Task-System mit signierten Celery-Aufgaben, Sharelink-Bundles und geteilte Saved Views. Die Live-Aktualisierung der Dokumentliste kam erst mit 3.0.0 offiziell dazu.

Geändert hat sich vor allem das KI-Modul, das in den Release Notes schlicht „Paperless AI“ heißt. Der Vektorspeicher für Dokument-Chat und ähnliche Dokumente lief in der ersten Beta mit FAISS, wechselte im Juni kurz auf LanceDB und landete dann bei sqlite-vec, einer einzelnen SQLite-Datei. Der Grund steht im Issue (#12970): LanceDB brach auf CPUs ohne AVX2 mit einem Absturz ab, und solche CPUs stecken in vielen kleinen NAS-Geräten, also genau dort, wo paperless-ngx gern läuft. Wer die Beta mit KI getestet hat, löscht den alten Index und baut ihn neu auf.

Dazu kamen bis zum Stable Embeddings über Ollama, einstellbare Chunk-Größe und Kontextfenster sowie ein Timeout für langsame Modelle. Das hilft vor allem bei lokalen Modellen auf schwächerer Hardware.

Die ersten Wochen

Version 3.0.1 vom 23. Juli enthielt einen Fehler in den Datenbank-Migrationen und startete nicht. Am nächsten Tag kam 3.0.2. Wer heute updatet, betrifft das nicht mehr, aber es zeigt, warum wir bei Major-Versionen ein paar Patch-Releases abwarten.

Danach ging es ruhiger weiter. Die Patch-Releases bis 3.0.5 beheben vor allem Feinheiten der neuen Suche (alte Whoosh-Schreibweisen wie yrs in Datumsabfragen) und der OCR-Erkennung. Zwei Sicherheitshinweise hat das Projekt seit Mai veröffentlicht:

  • Path Traversal bei der Dateinamensbildung, wenn FILENAME_FORMAT_REMOVE_NONE aktiv ist, niedrig eingestuft, behoben in 3.1.2 (GHSA-2jhj-xqrq-rmrq).
  • Über KI-Klassifizierungs-Workflows konnten Informationen aus Dokumenten ohne Besitzer bei anderen Nutzern landen. Mittel eingestuft, behoben in 3.3.2 (GHSA-c8f3-pqr2-rr24).

Dazu kam 3.3.4 mit aktualisierten Abhängigkeiten, unter anderem wegen Lücken in Pillow und aiohttp; das Projekt empfiehlt dieses Update allen Nutzern. Unsere Empfehlung ist deshalb einfach: Updaten Sie direkt auf 3.4.1, nicht auf eine frühe 3.0.x.

Was 3.1 bis 3.4 nachgelegt haben

Die Minor-Releases seit August sind keine Pflege-Versionen. Sie bringen Funktionen, die im Alltag auffallen.

Workflows mit KI. Seit 3.1 gibt es die Workflow-Aktion „Apply AI suggestions“. Die KI-Vorschläge für Titel, Korrespondent, Dokumenttyp und Tags lassen sich damit automatisch auf neue Dokumente anwenden, nicht nur auf Knopfdruck. Damit schließt das eingebaute Modul die größte Lücke zum separaten Paperless-AI.

Versionen nachträglich bilden. Ebenfalls seit 3.1 lassen sich vorhandene Dokumente zu Versionen eines Dokuments zusammenführen. Für Altbestände, in denen dieselbe Vertragsfassung dreimal als eigenes Dokument liegt, ist das die eigentlich nützliche Hälfte der Versionierung.

Freigaben im Blick. 3.2 bringt eine zentrale Übersicht aller Share-Links und Bundles. Wer externen Beratern regelmäßig Unterlagen freigibt, sieht dort, welche Links noch offen sind. Dazu kommen ein Filter für Duplikate und eine Suche, die wieder die alte Whoosh-Syntax versteht.

3.3 sichert den Django-Admin mit Zwei-Faktor-Anmeldung ab und macht Barcode-Inhalte durchsuchbar. 3.4 erlaubt Custom Fields in Titelvorlagen von Workflows und erzeugt PDF-Vorschaubilder über poppler; ImageMagick fällt als Abhängigkeit weg.

Vor dem Update

Die offizielle Migrationsanleitung ist knapp und vollständig. Die Punkte, an denen es in der Praxis hakt:

Nur von 2.20.15 aus. Version 3 lässt sich ausschließlich von 2.20.15 aus installieren. Ältere Installationen gehen erst auf diese Version, starten einmal sauber und gehen dann weiter.

PAPERLESS_SECRET_KEY ist Pflicht. Version 3 verlangt einen ausdrücklich gesetzten Schlüssel, der Beispielwert aus der Doku wird abgelehnt. Wer bisher ohne eigenen Schlüssel lief, entscheidet: alten Standardwert explizit setzen, dann bleiben Sitzungen und Tokens gültig, oder einen neuen setzen und alle neu anmelden lassen.

Datenbank-Engine angeben. Mit PostgreSQL oder MariaDB muss PAPERLESS_DBENGINE gesetzt sein, für PostgreSQL mit dem Wert postgresql. Die SSL- und Pool-Einstellungen wandern nach PAPERLESS_DB_OPTIONS; die alten Variablen laufen vorerst mit Warnung weiter.

OCR und Archivdatei sind getrennt. Die alten Werte von PAPERLESS_OCR_MODE und PAPERLESS_OCR_SKIP_ARCHIVE_FILE werden nicht übernommen. Die Umrechnung:

bisherab Version 3
PAPERLESS_OCR_MODE=skip_noarchivePAPERLESS_OCR_MODE=auto und PAPERLESS_ARCHIVE_FILE_GENERATION=never
PAPERLESS_OCR_SKIP_ARCHIVE_FILE=neverPAPERLESS_ARCHIVE_FILE_GENERATION=always
PAPERLESS_OCR_SKIP_ARCHIVE_FILE=with_textPAPERLESS_ARCHIVE_FILE_GENERATION=auto (neuer Standard)
PAPERLESS_OCR_SKIP_ARCHIVE_FILE=alwaysPAPERLESS_ARCHIVE_FILE_GENERATION=never

Werte, die über die Einstellungen in der Oberfläche gesetzt wurden, migriert paperless-ngx selbst.

Eigene Skripte umstellen. Pre- und Post-Consume-Skripte bekommen keine positionalen Argumente mehr, nur noch Umgebungsvariablen. Aus $1 wird DOCUMENT_SOURCE_PATH, beim Post-Consume-Skript aus $1 bis $8 die Variablen DOCUMENT_ID bis DOCUMENT_TAGS. Ein Skript, das seit Jahren unauffällig Rechnungen an die Buchhaltung meldet, meldet nach dem Update ebenso unauffällig nichts mehr. Genau diese Skripte prüfen wir zuerst.

Schnittstelle ab Version 9. API-Versionen unter 9 sind entfernt, aktuell ist Version 10. Ältere Apps, Scanner-Anbindungen und eigene Integrationen vorher gegen eine Testinstanz prüfen.

Verschlüsselung vorher auflösen. Die alte Dokument- und Thumbnail-Verschlüsselung gibt es nicht mehr. Wer sie genutzt hat, führt vor dem Update decrypt_documents aus und verschlüsselt stattdessen das Speichervolumen.

Dazu kommen Änderungen, die nichts kaputt machen, aber das Verhalten ändern:

  • Duplikate werden nicht mehr abgelehnt, sondern angenommen und in der Oberfläche markiert. Das alte Verhalten kommt mit PAPERLESS_CONSUMER_DELETE_DUPLICATES=true zurück.
  • In der Suche heißt note: jetzt notes.note: und custom_field: jetzt custom_fields.value:. Gespeicherte Ansichten werden migriert, die Gewohnheiten der Nutzer nicht.
  • Hinter einem Reverse Proxy braucht es unter Umständen PAPERLESS_TRUSTED_PROXIES, sonst endet die Anmeldung mit einem 403.
  • Die Consumer-Variablen sind teils umbenannt, aus CONSUMER_POLLING wird zum Beispiel CONSUMER_POLLING_INTERVAL. CONSUMER_IGNORE_PATTERNS erwartet jetzt reguläre Ausdrücke.
  • Die Task-Historie wird beim Update gelöscht.
  • Barcodes liest nur noch zxing-cpp, die Einstellung CONSUMER_BARCODE_SCANNER entfällt.

Eine Hürde liegt in der Hardware. Die mitgelieferten NumPy-Pakete setzen eine CPU mit x86-64-v2 voraus, also mindestens SSE4.2. Betroffen sind laut Projekt vor allem frühe Atom- und Celeron-Chips sowie AMD-Prozessoren vor 2011. Dort stürzt der Klassifikator ab, und zwar im Takt seines stündlichen Trainings, was die Fehlersuche so angenehm macht wie einen Wackelkontakt. Der Ausweg PAPERLESS_TRAIN_TASK_CRON=disable schaltet die automatische Zuordnung ab. Auf solchen Geräten ist das Update eher ein Anlass, über neue Hardware nachzudenken.

Der Ablauf

So gehen wir bei Kunden vor:

  1. Sichern. Datenbank-Dump, Medienverzeichnis und zusätzlich ein Export mit document_exporter. Der Export ist die Rückfallebene, die von der Datenbankversion unabhängig ist.
  2. Auf 2.20.15 bringen, falls noch nicht geschehen, und einmal sauber starten lassen.
  3. Testinstanz aufsetzen mit einer Kopie der Daten und der neuen Umgebung: Secret Key, Datenbank-Engine, OCR- und Archiv-Variablen, umbenannte Consumer-Variablen.
  4. Auf 3.4.1 updaten und den ersten Start beobachten. Der Suchindex wird automatisch neu aufgebaut, weil das Tantivy-Format zum alten nicht passt. Bei großen Archiven dauert das. Messen Sie die Zeit, sie gilt später auch für die Produktivinstanz. Bei Installationen ohne Docker laufen manage.py migrate, document_index reindex --if-needed und document_llmindex migrate von Hand.
  5. Prüfen: eigene Skripte, Scanner- und Mail-Eingang, API-Clients, gespeicherte Suchen, Anmeldung über den Proxy und, falls eingerichtet, die OIDC-Anmeldung.
  6. Produktiv updaten mit denselben Variablen und derselben Reihenfolge.

Die KI schalten wir bewusst nicht im selben Schritt ein. Sie ist standardmäßig aus und bleibt es, bis das Update stabil läuft.

Die KI einschalten

Das eingebaute Modul wird über PAPERLESS_AI_ENABLED aktiviert. Als Sprachmodell dient entweder ein lokales Modell über Ollama oder ein Dienst mit OpenAI-kompatibler Schnittstelle. Für die Embeddings stehen Ollama, HuggingFace (lokal) oder ebenfalls ein OpenAI-kompatibler Dienst zur Wahl. Den Vektorindex baut paperless-ngx nachts selbst auf, gesteuert über PAPERLESS_LLM_INDEX_TASK_CRON; von Hand geht es mit document_llmindex rebuild.

Für Unternehmensdokumente empfehlen wir den lokalen Weg mit Ollama. Rechnungen, Verträge und Personalunterlagen verlassen dann das Haus nicht. Ein externer Dienst ist eine bewusste Entscheidung mit Auftragsverarbeitung, keine Voreinstellung. Und wer KI in Workflows nutzt, sollte mindestens auf 3.3.2 sein, siehe den Sicherheitshinweis oben.

Wie wir das machen

Wir betreuen paperless-ngx als selbst gehostetes Dokumentenmanagement für Unternehmen im Großraum München. Das Update auf Version 3 führen wir mit Testinstanz, angepassten Skripten und einem vereinbarten Zeitfenster durch, damit am nächsten Morgen der Posteingang wieder läuft. Einführung, Umzug und Betrieb beschreibt unsere Angebotsseite zu paperless-ngx.

Lieber direkt fragen?

Wir antworten persönlich.