Paperless NGX 3.0: Native KI-Funktionen im Praxis-Test

Mit Paperless NGX 3.0 wandert die KI endlich da hin, wo sie eigentlich hingehört: direkt in den Core. Bisher musstest du dir die Funktion über einen extra Container wie Paperless GPT oder Paperless AI dazustricken, in 3.0 hinterlegst du in den Einstellungen ein LLM-Backend, wählst ein Einbettungsmodell und lässt Tags, Korrespondenten, Dokumenttypen und Titel direkt am Dokument per Klick generieren.

Und das ist nicht mal alles: Mit derselben Konfiguration bekommst du obendrauf einen RAG-Chat, der dein komplettes Dokumentenarchiv durchsuchbar macht – inklusive verlinkter Quellen unter jeder Antwort. Ich habe Paperless 3.0 einmal mit OpenRouter und einmal mit lokalem Ollama verbunden und geschaut, was die nativen KI-Funktionen heute wirklich abliefern – mit einer Überraschung, die ich beim ersten Schreiben dieses Beitrags glatt übersehen hatte.

Wichtiger Nachtrag zum Video: Den RAG-Chat über deinen kompletten Dokumentenbestand — die wohl spannendste KI-Funktion in Paperless NGX 3.0 — habe ich erst NACH der Aufnahme entdeckt. Im Video kommt sie deshalb (noch) nicht vor. Wie der Chat funktioniert, was er kann und wo das Sprechblasen-Icon sitzt, findest du weiter unten im Abschnitt „Chat mit deinem kompletten Dokumentenbestand (RAG)“.

Stand 24.07.2026: Paperless NGX 3.0 ist seit dem 22. Juli offiziell veröffentlicht, aktuell in Version 3.0.2. Die Beta-Phase ist damit vorbei. Meine Hands-on-Tests und die Screenshots in diesem Beitrag sind allerdings auf dem Release Candidate entstanden. Wo das fertige Release Dinge anders macht als die Vorabversion, habe ich das im Text markiert und anhand der offiziellen Release Notes und Dokumentation aktualisiert. Ein komplett neues Video zur fertigen 3.0 ist in Arbeit.

Was ist neu an Paperless NGX 3.0?

Version 3.0 bringt mehrere Änderungen, der für viele aber spannendste Punkt sind die nativen KI-Funktionen:

• Ein neuer Reiter „KI-Einstellungen“ unter Konfiguration
• Wahl zwischen openai-like und ollama-like als LLM-Backend
• Konfiguration von Einbettungsmodell (Vektor-Gedächtnis) und Haupt-LLM (Textverständnis)
• Im geöffneten Dokument: Button „Vorschlagen“ — KI generiert Tags, Dokumenttyp, Korrespondent, Titel, im finalen Release zusätzlich Speicherpfad und Datum
• RAG-Chat über deinen kompletten Dokumentenbestand – Antwort plus klickbare Quellverweise auf die zugrundeliegenden Belege
• Einstellbare Ausgabesprache für die Vorschläge – ohne eigene Angabe folgt die KI deiner Oberflächensprache

Wichtig vorab: Auch das fertige Release bringt nicht alles mit, was man sich von Paperless 3.0 wünscht. Das vollautomatische Klassifizieren beim Consumer-Upload fehlt weiterhin – die KI-Vorschläge sind ausdrücklich als Funktion gebaut, die du pro Dokument anforderst. Mehr dazu weiter unten.

KI in der Praxis: Der „Vorschlagen“-Button

So weit die Konfiguration. Spannender ist, was am Ende rauskommt. In jedem geöffneten Dokument findest du in der rechten Seitenleiste den Button „Vorschlagen“ (im Video gut zu sehen). Ein Klick darauf, ein paar Sekunden warten – und Paperless präsentiert dir eine Liste an Vorschlägen, die du einzeln per Klick übernehmen kannst:

• Tags: im Test waren 9 Vorschläge dabei, darunter „Tickets“ und „Event“ – passend und brauchbar.
• Dokumenttyp: wird sauber erkannt (z. B. „Ticket“).
• Korrespondent: wird vorgeschlagen, sofern aus dem OCR-Text ableitbar.
• Titel: wird – etwas versteckt – ebenfalls von der KI generiert. Das war im Test eine angenehme Überraschung.

Die Qualität der Vorschläge hängt erwartungsgemäß stark vom gewählten LLM ab. gpt-4o-mini und gemini-2.5-flash haben in meinen Tests souverän abgeliefert, kleinere lokale Modelle (llama3.2:1b, qwen2.5:0.5b) liegen vor allem bei Korrespondenten und Titeln deutlich öfter daneben.

Chat mit deinem kompletten Dokumentenbestand (RAG)

Und jetzt das eigentliche Killer-Feature, das ich beim ersten Schreiben dieses Beitrags glatt übersehen hatte: Paperless 3.0 spricht mit dir – über deine Dokumente. Oben rechts im Header sitzt ein neues Sprechblasen-Icon. Ein Klick darauf öffnet ein Chat-Fenster mit dem schlichten Prompt „Eine Frage zu einem Dokument stellen…“ – gemeint sind aber alle Dokumente, nicht nur das gerade geöffnete.

Im Hintergrund läuft klassisches RAG (Retrieval Augmented Generation): Paperless durchsucht dein Vektor-Gedächtnis nach den thematisch passendsten Belegen, schickt sie zusammen mit deiner Frage ans LLM und liefert dir nicht nur die Antwort, sondern auch eine Liste der Dokumente, aus denen sie stammt – als klickbare Kacheln direkt unter dem Text.

Drei Beispiele aus meinen eigenen Belegen:

• „Was hat ein Mac Mini 2014 ungefähr gekostet?“ — Antwort: „Ein Mac Mini 2014 kann für etwa 80 Euro erworben werden.“ mit Verlinkung auf den passenden Beleg.
• „Wie schalte ich das Walkie-Talkie ein?“ — präzise Bedienanleitung aus der eingescannten Geräte-Anleitung, inklusive Quell-Dokument.
• „Wie viel zahle ich für Morningfame Plus?“ — „10,84 USD monatlich“ plus Liste der drei zugrundeliegenden Rechnungen (06.25, 10.25, 11.25).

In der Praxis bedeutet das: Du musst nicht mehr durch hundert PDFs scrollen, um nachzuschauen, was du im März bei welchem Anbieter gezahlt hast oder welcher Geräte-Code in welcher Anleitung steht. Du fragst – Paperless antwortet und zeigt dir die Originalbelege dazu. Genau diese Funktion wünschen sich viele Leute seit Jahren von Paperless, und sie ist schon erstaunlich rund.

Voraussetzung dafür ist allerdings, dass dein Einbettungsmodell sauber durchgelaufen ist: Beim ersten Aktivieren der KI baut Paperless im Hintergrund einen Vektor-Index über deinen kompletten Bestand auf. Bei größeren Archiven darf das gern ein paar Minuten dauern – danach sind die Antworten aber wirklich flott. Zwei Dinge haben sich hier seit dem Release Candidate geändert: Der Index liegt jetzt in einer SQLite-Datenbank auf Basis von sqlite-vec statt in einem FAISS-Index, und er aktualisiert sich per Zeitplan täglich von allein.

Der Pain Point: Was Paperless 3.0 heute noch nicht kann

So weit die guten Nachrichten. Beim automatischen Klassifizieren neuer Uploads zeigt Paperless 3.0 dann aber seine Kanten: Es bleibt viel manuelle Klickarbeit. Konkret:

• Beim Upload neuer Dokumente (Consumer / Drag&Drop / API) werden keine KI-Vorschläge automatisch erzeugt. Frisch hochgeladene Dokumente liegen ohne Tag, ohne Typ, ohne Korrespondent da.
• Es gibt keinen Schalter im UI, der „bei Upload automatisch klassifizieren“ aktiviert.
• Die KI ändert nichts selbstständig – jeder einzelne Vorschlag muss per Hand übernommen werden.

In der Praxis heißt das: Für Bestandsdokumente (klick-für-klick durchgehen, KI-Vorschläge prüfen, übernehmen) ist 3.0 ein riesiger Komfortgewinn. Für den klassischen Stapel-Workflow – Belege scannen, in den Consumer-Ordner werfen, der Rest erledigt sich von selbst – brauchst du heute weiterhin externe Tools.

Paperless 3.0 native KI vs. Paperless GPT / Paperless AI

Damit ergibt sich eine klare Einordnung gegenüber den etablierten Drittanbieter-Tools:

Für wen lohnt sich der Wechsel auf 3.0?

• Du arbeitest viele Bestandsdokumente händisch auf und willst die KI nur als „Vorschlag-Assistent“ – sehr empfehlenswert.
• Du willst dein Archiv durchfragen statt es zu durchsuchen („Was habe ich letztes Jahr für Strom gezahlt?“, „In welcher Anleitung stand nochmal Schritt X?“) – sehr empfehlenswert, der RAG-Chat ist genau dafür gebaut.
• Du möchtest ohne zusätzlichen Container auskommen und ein cleanes Setup bauen – empfehlenswert, sofern du mit der Klick-Arbeit beim Upload leben kannst.
• Du brauchst vollautomatische Verarbeitung beim Consumer-Upload (z. B. der ScanSnap-Import landet fertig getaggt in der Inbox) – dann bleib vorerst bei Paperless GPT oder Paperless AI.

Fazit zu Paperless 3.0

Dass Paperless die KI-Funktionen jetzt selbst mitbringt, war überfällig. Bisher musste sich jeder seine eigene Lösung aus Paperless GPT, Paperless AI und etwas Geduld zusammenstricken — in Paperless NGX 3.0 sind das ein paar Felder in den Einstellungen. Und mit dem RAG-Chat über den kompletten Dokumentenbestand liegt obendrauf noch ein Feature, das viele Drittanbieter-Tools in dieser Form gar nicht haben – das hatte ich beim ersten Test glatt übersehen und musste meinen eigenen Beitrag deswegen nachträglich nochmal aufmachen.

Was auch im fertigen Release fehlt, ist die automatische Klassifizierung beim Upload: dass die KI von allein anspringt, wenn ein neues Dokument im Consumer-Ordner landet. Auch ein Bulk-Modus für ganze Stapel und ein bisschen UX-Liebe an der Vorschlagsmaske würden nicht schaden.

Mein Fazit hat sich im Laufe dieses Beitrags deshalb verschoben: Wer sein Archiv vor allem durchfragen oder Bestandsdokumente händisch sauber bekommen will, kann mit 3.0 richtig viel anfangen. Für rein neue Belege im Daily Driver bleibt Paperless GPT / Paperless AI vorerst die runderere Wahl – aber der Abstand schrumpft. Wenn du Lust auf einen eigenen Test hast, findest du im nächsten Abschnitt das komplette Setup, mit dem du in einer Viertelstunde durchspielen kannst, was oben beschrieben ist.

Du willst Paperless 3.0 selbst testen? Hier ist das komplette Setup

Wenn du nach dem Realitätscheck oben sagst „interessant genug, ich will’s selbst sehen“ – hier ist alles, was du brauchst: die docker-compose.yaml, die ich für den Test einsetze, plus die beiden funktionierenden KI-Konfigurationen (OpenRouter oder lokales Ollama). Wenn du nur entscheiden wolltest, ob sich der Wechsel lohnt: Du kannst hier aufhören.

Testumgebung mit Docker Compose

Bau dir am besten eine isolierte Test-Instanz auf, statt deine produktive Installation direkt anzufassen. Paperless 3.0 bringt eine Reihe von Breaking Changes mit, unter anderem einen umgebauten Consumer, einen neuen Suchindex (tantivy statt Whoosh) und das Aus für API-Version 1. Für das Upgrade einer bestehenden Installation gilt deshalb: vorher ein Backup ziehen und den offiziellen Migration Guide zu v3 lesen. Die sechs häufigsten Stolperfallen beim Update habe ich inzwischen ganz unten im Beitrag zusammengefasst. In einer separaten Instanz kannst du die KI-Funktionen dagegen ohne Risiko für deine Daten durchspielen. Wie du auf einem ZimaOS-Server am einfachsten zwei Paperless-Instanzen parallel betreibst, zeige ich dir Schritt für Schritt in meinem Beitrag „Zwei Paperless NGX Instanzen auf einem ZimaOS Server betreiben“.

Hier ist die docker-compose.yaml, die ich für den Test verwende – hier bereits auf das aktuelle Tag 3.0.2 gehoben. Sie legt alle Volumes unter /DATA/AppData/paperless ab (passt sehr gut zu ZimaOS, lässt sich aber auch in Portainer oder pur per Docker Compose ausführen):

version: "3.4"
services:

  broker:
    image: redis:latest
    restart: unless-stopped
    volumes:
      - /DATA/AppData/paperless/redis:/data

  db:
    image: mariadb:latest
    restart: unless-stopped
    environment:
      - MARIADB_DATABASE=paperless
      - MARIADB_USER=paperless
      - MARIADB_PASSWORD=paperless
      - MARIADB_ROOT_PASSWORD=paperless
    volumes:
      - /DATA/AppData/paperless/postgres:/var/lib/mysql

  gotenberg:
    image: docker.io/gotenberg/gotenberg:latest
    restart: unless-stopped
    command:
      - gotenberg
      - --chromium-disable-javascript=true
      - --chromium-allow-list=file:///tmp/.*
    ports:
      - "3006:3000"

  tika:
    image: apache/tika:latest
    restart: unless-stopped
    ports:
      - "9998:9998"

  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:3.0.2
    restart: unless-stopped
    depends_on:
      - broker
      - db
    ports:
      - "8006:8000"
    volumes:
      - /DATA/AppData/paperless/data:/usr/src/paperless/data
      - /DATA/AppData/paperless/media:/usr/src/paperless/media
      - /DATA/AppData/paperless/export:/usr/src/paperless/export
      - /DATA/AppData/paperless/consume:/usr/src/paperless/consume
    environment:
      - PAPERLESS_REDIS=redis://broker:6379
      - PAPERLESS_DBENGINE=mariadb
      - PAPERLESS_DBHOST=db
      - PAPERLESS_DBUSER=paperless
      - PAPERLESS_DBPASS=paperless
      - PAPERLESS_DBPORT=3306
      - PAPERLESS_TIKA_ENABLED=1
      - PAPERLESS_TIKA_ENDPOINT=http://tika:9998
      - PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://gotenberg:3000
      - PAPERLESS_TIME_ZONE=Europe/Berlin
      - PAPERLESS_ADMIN_USER=paperless
      - PAPERLESS_ADMIN_PASSWORD=paperless
      - PAPERLESS_SECRET_KEY=DeinSehrGeheimerSchluessel123!
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 5

networks:
  default:
    name: paperless_default

Nach docker compose up -d erreichst du Paperless unter http://<deine-server-ip>:8006. Login mit paperless / paperless. Passwort und PAPERLESS_SECRET_KEY bitte vor dem produktiven Einsatz ändern.

KI-Einstellungen aktivieren

Sobald Paperless läuft, klickst du auf dein Benutzer-Icon, dann auf Konfiguration und schließlich auf den Tab KI-Einstellungen. Hier aktivierst du die KI über den Schalter ganz oben und füllst anschließend zwei Blöcke aus:

1. Sprachmodell (LLM) – das „Gehirn“, das Text liest und Vorschläge generiert.
2. Einbettungsmodell (Embedding) – das Vektor-Gedächtnis, mit dem Paperless ähnliche Dokumente findet.

Ein Hinweis zur Einordnung: Im Release Candidate, auf dem meine Tests unten laufen, gab es nur ein zentrales Endpunkt-Feld für LLM und Embedding-Modell – Cloud-LLM plus lokales Embedding war damit nicht möglich. Im finalen Release hat das Einbettungsmodell laut Dokumentation ein eigenes Endpunkt-Feld bekommen und greift nur dann auf den LLM-Endpunkt zurück, wenn du es leer lässt. Hybrid-Setups sind also inzwischen machbar. Die beiden Konfigurationen unten bleiben trotzdem der schnellste Weg ans Ziel.

Variante A: OpenRouter via API (schnell, aber die Texte gehen in die Cloud)

Wenn dein Paperless auf einem stromsparenden NAS, einem Mini-PC oder generell ohne dicke Grafikkarte läuft, ist das die Variante, die in der Praxis wirklich funktioniert. Statt deine CPU mit den KI-Berechnungen ins Timeout (Fehler 500) zu treiben, lagert OpenRouter die Arbeit auf fremde Hardware aus. Die Antworten kommen in Millisekunden zurück, dafür landen die Textdaten deiner Dokumente eben in der Cloud.

So sehen die Einstellungen aus:

• LLM-Backend: openai-like
• LLM-Modell: z. B. openai/gpt-4o-mini oder google/gemini-2.5-flash (bei OpenRouter immer das Hersteller-Präfix vor den Modellnamen schreiben!)
• LLM Einbettungs-Backend: openai-like
• LLM-Einbettungsmodell: openai/text-embedding-3-small (extrem günstig und schnell für das Vektor-Gedächtnis)
• LLM-Endpunkt: https://openrouter.ai/api/v1
• LLM API-Schlüssel: dein persönlicher OpenRouter-Key (beginnt mit sk-or-v1-…)

Anschließend in OpenRouter unter Settings > Credits ein paar Euro aufladen – für ein paar hundert Dokumente reichen 1–2 € locker.

Variante B: Lokales Ollama (alles bleibt im Haus, dafür langsamer)

Bei dieser Variante verlassen deine Dokumente niemals dein Heimnetzwerk. Paperless spricht direkt mit deinem lokalen Ollama-Container. Der Haken: Textgenerierung ist rechenintensiv. Lässt du Ollama rein über die CPU laufen, solltest du auf kleine, schnelle Modelle setzen, sonst bricht Paperless die Anfrage wegen Zeitüberschreitung ab. Im Release Candidate lag dieses Limit fest bei 60 Sekunden. Im fertigen 3.0 sind es standardmäßig 120 Sekunden, und der Wert lässt sich in den KI-Einstellungen anpassen – für lokale Inferenz auf schwacher Hardware ist das die wichtigste Neuerung gegenüber der Vorabversion.

Modelle vorher per ollama pull bereitstellen, z. B.:

ollama pull llama3.2:1b
ollama pull nomic-embed-text

Dann in den KI-Einstellungen – das ist die Konfiguration, mit der mein Test gelaufen ist:

• LLM-Backend: openai-like (im Release Candidate war das der zuverlässigere Weg – siehe Hinweis unter der Liste)
• LLM-Modell: llama3.2:1b oder qwen2.5:0.5b (beides winzige, schnelle Modelle, die auch auf CPUs zügig antworten)
• LLM Einbettungs-Backend: openai-like
• LLM-Einbettungsmodell: nomic-embed-text (Standard-Vektormodell, vorher in Ollama per pull herunterladen)
• LLM-Endpunkt: http://<deine-server-ip>:11434/v1 (extrem wichtig: das /v1 am Ende muss zwingend stehen, damit Ollama die Anfragen von Paperless im OpenAI-Kompatibilitätsmodus versteht)
• LLM API-Schlüssel: ollama (Feld darf nicht leer sein, Inhalt egal – wird nicht geprüft)

Was sich seit dem Release Candidate geändert hat: Der Umweg über openai-like war ein Workaround. Im fertigen 3.0 ist ollama als eigenes Backend regulär dokumentiert; dann gibst du den Endpunkt direkt als http://<deine-server-ip>:11434 an, also ohne /v1. Beim Einbettungsmodell ist mit huggingface außerdem eine dritte Option dazugekommen, die das Modell direkt in Paperless lädt und ganz ohne Ollama auskommt. Beides habe ich noch nicht selbst durchgetestet – die Liste oben ist der Stand, den ich auch im Video zeige.

Pro-Tipp – Fehler 500 nach Modell- oder Variantenwechsel: Wenn du zuvor schon mit anderen Embedding-Modellen experimentiert hast (oder zwischen Variante A und B umschaltest) und beim Klick auf den KI-Zauberstab plötzlich einen hartnäckigen HTTP 500 kassierst, liegt das fast immer an einem Dimensions-Konflikt im Vektor-Index. Unterschiedliche Einbettungsmodelle nutzen unterschiedlich große Vektoren (z. B. 768 vs. 1536 Zahlen), und der alte Index passt dann nicht mehr zum neuen Modell.

Im Release Candidate half nur, das Index-Verzeichnis von Hand zu löschen und den Container neu zu starten. Das fertige 3.0 bringt dafür einen eigenen Befehl mit:

docker exec -it <paperless-container> document_llmindex rebuild

Der baut den Index von Grund auf neu – laut Dokumentation genau der vorgesehene Weg nach einem Wechsel von Einbettungs-Backend oder -Modell. Daneben gibt es document_llmindex update, das nur neue und geänderte Dokumente nachträgt, und document_llmindex compact, das belegten Speicherplatz wieder freigibt.

FAQ zu Paperless NGX 3.0 und den KI-Funktionen

Kann ich in Paperless NGX 3.0 mit meinen Dokumenten chatten?

Ja. Über das Sprechblasen-Icon oben rechts im Header öffnest du einen RAG-Chat über deinen kompletten Bestand. Paperless sucht intern per Vektor-Index die thematisch passendsten Belege heraus, schickt sie ans LLM und liefert dir die Antwort inklusive verlinkter Quelldokumente. Voraussetzung sind aktivierte KI-Einstellungen mit Sprach- und Einbettungsmodell – beim ersten Mal baut Paperless dafür im Hintergrund einen Vektor-Index über alle Dokumente auf.

Verarbeitet Paperless NGX 3.0 hochgeladene Dokumente automatisch mit KI?

Nein. Auch im fertigen 3.0 erzeugt Paperless keine automatischen KI-Vorschläge beim Upload. Du musst jedes Dokument öffnen und manuell auf „Vorschlagen“ klicken – die Dokumentation beschreibt die KI-Vorschläge ausdrücklich als Funktion, die pro Dokument angefordert wird. Auto-Klassifizierung beim Consumer-Upload ist nicht enthalten.

Welche Modelle kann ich in den KI-Einstellungen verwenden?

Du wählst ein Sprachmodell (LLM) und ein Einbettungsmodell. Im Release Candidate mussten beide zwingend über denselben Endpunkt laufen; seit dem finalen 3.0 hat das Einbettungsmodell ein eigenes Endpunkt-Feld, ein Hybrid aus Cloud-LLM und lokalem Embedding ist damit möglich. Am einfachsten bleibt es trotzdem, sich für einen Weg zu entscheiden: entweder OpenRouter (schnell, Cloud, z. B. openai/gpt-4o-mini + openai/text-embedding-3-small) oder ein lokales Ollama (Datenschutz, z. B. llama3.2:1b + nomic-embed-text). In beiden Fällen wählst du openai-like als Backend; bei Ollama muss am Endpunkt zwingend /v1 angehängt werden.

Ist Paperless NGX 3.0 stabil genug für den produktiven Einsatz?

Ja. Paperless NGX 3.0 ist seit dem 22. Juli 2026 offiziell veröffentlicht – die Beta-Phase ist vorbei. Beim Upgrade einer bestehenden Installation solltest du trotzdem die Breaking Changes im Blick behalten: 3.0 baut unter anderem den Consumer um, wechselt den Suchindex und entfernt API-Version 1. Vorher ein Backup ziehen und den offiziellen Migration Guide lesen. Wenn du nur die KI-Funktionen ausprobieren willst, nimm die separate Test-Instanz mit eigener docker-compose.yaml von oben.

Dinge zu beachten beim Update von Paperless NGX 2.x auf 3.0

Stand 04.08.2026: Seit dem Release rollt die Update-Welle – und dabei zeigt sich, dass die Breaking Changes in 3.0 kein Kleingedrucktes sind, sondern echte Stolperfallen. Wenn du also nicht die Test-Instanz von oben nutzt, sondern deine bestehende Installation direkt auf 3.0 hebst, nimm dir vorher zwei Minuten für diese Liste. Grundlage ist der offizielle Migration Guide zu v3, eine sehenswerte Video-Zusammenfassung der häufigsten Fehler gibt es außerdem beim Kanal Digitalisierung mit Kopf.

Vorab, nicht verhandelbar: Backup ziehen. Und: Das Update auf 3.0 funktioniert nur von Version 2.20.15 aus. Ältere Installationen hebst du erst auf 2.20.15 und machst dann den Sprung.

Drei Fehler, die du sofort bemerkst

1. PAPERLESS_SECRET_KEY ist jetzt Pflicht. Ohne gesetzten Secret Key verweigert Paperless 3.0 den Start. Bisher gab es einen eingebauten Default – wer sich (unwissentlich) darauf verlassen hat, muss den Wert jetzt explizit setzen. Einen frischen Schlüssel erzeugst du mit python3 -c "import secrets; print(secrets.token_urlsafe(64))" – der loggt allerdings alle bestehenden Sessions aus. In meiner docker-compose.yaml oben ist der Key bereits gesetzt.

2. PAPERLESS_DBENGINE ist jetzt Pflicht. Bisher hat Paperless die Datenbank-Engine einfach aus PAPERLESS_DBHOST abgeleitet. In 3.0 musst du sie bei PostgreSQL und MariaDB explizit angeben (postgresql oder mariadb). Fehlt die Variable, fällt Paperless kommentarlos auf SQLite zurück und begrüßt dich nach dem Update mit einer leeren Instanz. Die Daten sind dann nicht weg – sie liegen unangetastet in deiner alten Datenbank –, aber der Schreck sitzt erstmal tief. Auch das hat die compose oben schon drin (PAPERLESS_DBENGINE=mariadb).

3. Die alten OCR-Settings fliegen raus. PAPERLESS_OCR_MODE=skip und skip_noarchive gibt es nicht mehr, PAPERLESS_OCR_SKIP_ARCHIVE_FILE ebenfalls nicht. Neu geregelt wird beides getrennt: PAPERLESS_OCR_MODE (auto/force/redo/off) steuert die Texterkennung, das neue PAPERLESS_ARCHIVE_FILE_GENERATION (auto/always/never) die Archiv-PDFs. Alte Werte werden nicht stillschweigend übernommen – Paperless loggt beim Start nur eine Warnung. Hast du die OCR-Einstellungen dagegen über das Admin-UI gepflegt, migriert 3.0 die Werte automatisch.

Drei stille Fallen, die du erst später bemerkst

4. Duplikate werden jetzt konsumiert statt abgewiesen. Bisher hat Paperless doppelt eingeworfene Dokumente schlicht abgelehnt. 3.0 nimmt sie an und markiert sie nur noch im UI als Duplikat. Wer seinen Scanner-Workflow darauf gebaut hat, dass Doppel-Scans von allein verschwinden, holt sich das alte Verhalten mit PAPERLESS_CONSUMER_DELETE_DUPLICATES=true zurück.

5. Consumer-Variablen wurden umbenannt. Der Consumer läuft in 3.0 auf einer neuen Bibliothek, mehrere Einstellungen heißen jetzt anders oder sind ersatzlos weg:

6. Pre- und Post-Consume-Skripte bekommen keine Positions-Argumente mehr. $1 bis $8 sind Geschichte, alle Infos kommen ausschließlich über Umgebungsvariablen (DOCUMENT_SOURCE_PATH, DOCUMENT_ID, DOCUMENT_TAGS und Co.). Skripte, die noch $1 auslesen, greifen ins Leere. Die Umgebungsvariablen gibt es allerdings schon seit v1.8 – das Umstellen ist meist in zwei Minuten erledigt.

Und eine Randnotiz für Langzeit-Nutzer: Die GPG-Verschlüsselung von Dokumenten (seit paperless-ng 0.9.3 deprecated) wird in 3.0 endgültig nicht mehr unterstützt. Falls deine Installation noch verschlüsselte Dokumente enthält, führe vor dem Update einmal decrypt_documents aus.