Paperless-ngx: Speicherpfade und Ordnerstruktur einrichten

Wenn du in Paperless-ngx ein Dokument hochlädst, speichert die Software es auf der Festplatte als 0000001.pdf. Im Browser siehst du davon nichts, dort heißt das Dokument weiterhin “Stromrechnung September 2026”. Auf dem Server sieht das Ganze anders aus, und das merkst du spätestens bei einem Backup oder wenn du die Dateien ohne Paperless brauchst.

Hier richte ich eine Ordnerstruktur mit lesbaren Dateinamen ein. Dafür gibt es zwei Werkzeuge: einen globalen Standard (PAPERLESS_FILENAME_FORMAT) und Speicherpfade, die du pro Dokumentgruppe festlegst. Ich zeige beides an einem laufenden Paperless-ngx 3.4 mit Beispieldokumenten.

Was Paperless standardmäßig ablegt

Ohne Einstellung landen alle Originale im Ordner media/documents/originals, nummeriert nach der internen ID:

media/documents/originals/0000001.pdf
media/documents/originals/0000003.pdf
media/documents/originals/0000004.pdf
media/documents/archive/0000004.pdf

Der Ordner archive enthält die durchsuchbare PDF/A-Version, die Paperless nach der Texterkennung erzeugt. Beide Ordner liegen im Volume, das du in der compose.yaml als media eingebunden hast.

Das ist kein Fehler. Paperless findet seine Dokumente über die Datenbank und braucht keine schönen Namen. Eine Struktur lohnt sich aber, wenn du:

• Dateien direkt vom Server oder per Backup einzeln herausholen willst,
• Paperless später wechseln möchtest und die Ablage dann noch verstehen sollst,
• Dokumente per Samba oder Nextcloud-Sync zusätzlich als normale Ordner brauchst.

Eine wichtige Regel vorab

Verschiebe oder benenne Dateien im Ordner media nie von Hand. Paperless merkt sich den Dateinamen jedes Dokuments. Ändert sich die Datei auf der Platte, meldet der Dokumenten-Check sie als fehlend.

Alle Änderungen laufen über Paperless selbst. Das Programm benennt die Dateien um, sobald du ein Dokument speicherst oder einen Speicherpfad änderst. Mach vor größeren Umbauten ein Backup, wie es hier beschrieben ist.

Der globale Standard: PAPERLESS_FILENAME_FORMAT

Die einfachste Variante ist eine Vorlage für alle Dokumente. Du trägst sie in der .env neben deiner compose.yaml ein:

PAPERLESS_FILENAME_FORMAT={{ created_year }}/{{ correspondent }}/{{ title }}

Das ergibt Ordner nach Jahr, darunter Ordner nach Korrespondent, und als Dateiname den Titel. Paperless hängt die Endung selbst an. Damit die Änderung greift, starte den Container neu:

sudo docker compose up -d paperless

Neue Dokumente nutzen die Vorlage sofort. Bereits vorhandene Dokumente bleiben zunächst, wo sie sind. Für sie startest du den Renamer:

sudo docker compose exec paperless document_renamer

Das Skript geht alle Dokumente durch und verschiebt jede Datei an den Platz, den die aktuelle Vorlage vorgibt. Bei mir sind das zwölf Dokumente in unter einer Sekunde.

Platzhalter

Du kannst diese Platzhalter in der Vorlage nutzen:

Fehlt bei einem Dokument zum Beispiel der Korrespondent, steht dort none im Pfad. Mit PAPERLESS_FILENAME_FORMAT_REMOVE_NONE=true lässt Paperless solche Teile weg, samt dem Leerzeichen davor.

Zwei Dokumente mit demselben Pfad bekommen automatisch den Zusatz _01, _02 und so weiter. Zeichen wie / oder : in Titeln ersetzt Paperless durch einen Bindestrich.

Setze nicht {{ tag_list }} in lange Pfade. Betriebssysteme begrenzen die Pfadlänge, und Paperless behält dann den alten Pfad bei.

Speicherpfade: unterschiedliche Regeln pro Dokumentgruppe

Eine einzige Vorlage passt selten für alles. Rechnungen möchtest du nach Monat sortieren, Verträge nach Vertragspartner, Steuerunterlagen nach Jahr. Dafür gibt es Speicherpfade. Jeder Speicherpfad hat einen Namen und eine eigene Vorlage mit denselben Platzhaltern.

Du findest sie unter Attribute → Speicherpfade. Ich habe drei angelegt:

Zum Anlegen klickst du auf Erstellen, vergibst einen Namen und trägst die Vorlage ein. Das Feld Zuweisungsalgorithmus lasse ich auf “Keiner”. Die Zuweisung übernehmen Workflows, dazu unten mehr.

Vorschau im Dialog

Im Bearbeiten-Dialog gibt es ein ausklappbares Feld Vorschau. Du wählst darin ein vorhandenes Dokument aus und siehst sofort, wohin es mit dieser Vorlage wandern würde:

Nutze die Vorschau, bevor du speicherst. Sobald du speicherst, verschiebt Paperless alle Dokumente mit diesem Speicherpfad.

Einem Dokument einen Speicherpfad geben

Im Dokument selbst gibt es unter Details das Feld Speicherpfad. Dort wählst du den Pfad aus und speicherst. Paperless benennt die Datei sofort um.

Du kannst auch mehrere Dokumente in der Liste markieren und über die Massenbearbeitung einen Speicherpfad setzen.

Speicherpfade automatisch zuweisen

Von Hand zuweisen ist bei hundert Dokumenten mühsam. Ich lasse deshalb die Workflows das erledigen. Die Aktion Zuweisung hat ein Feld für den Speicherpfad. Mein Workflow “Rechnungen automatisch kennzeichnen” setzt dort neben Tag und Dokumenttyp auch den Speicherpfad “Rechnungen”.

Alternativ geht auch der Zuweisungsalgorithmus am Speicherpfad selbst, etwa “Beliebiges Wort” mit Rechnung. Der Workflow ist übersichtlicher, weil Tag, Typ und Pfad an einer Stelle stehen.

Das Ergebnis auf dem Server

Nach der Zuweisung und mit dem globalen Standard {{ created_year }}/Sonstiges/{{ title }} für alles ohne Speicherpfad sieht der Ordner originals bei mir so aus:

2026/Sonstiges/Kontoauszug Oktober 2026.pdf
2026/Sonstiges/Notiz Steuer 2026.pdf
Rechnungen/2026/08 Praxis Dr. Meyer - Arztrechnung August 2026.pdf
Rechnungen/2026/09 Kabelnetz Nord AG - Internet September 2026.pdf
Rechnungen/2026/10 Nordlicht Energie GmbH - Stromrechnung September 2026.pdf
Rechnungen/2026/11 Haustechnik Nord GmbH - Heizungswartung 2026.pdf
Steuer/2026/Einkommensteuerbescheid 2025.pdf
Verträge/Hansa Versicherung AG/Hausratversicherung.pdf
Verträge/Haustechnik Nord GmbH/Wartungsvertrag Heizung.pdf
Verträge/Hausverwaltung Lindenhof/Mietvertrag Wohnung 4B.pdf

Dokumente mit Speicherpfad folgen dessen Vorlage. Alles andere fällt auf den globalen Standard zurück. Der Ordner archive bekommt dieselbe Struktur.

Ordnerstruktur planen

Lege die Struktur an, bevor du Hunderte Dokumente importierst. Ein Umbau ist zwar möglich, aber jede Änderung verschiebt viele Dateien.

• Sortiere die Ordner nach dem, was sich nie ändert: Dokumenttyp und Jahr.
• Der Dateiname enthält, was du beim Durchsuchen im Dateimanager brauchst: Datum, Korrespondent, Titel.
• Verträge laufen über Jahre. Hier ordnest du nach Vertragspartner, nicht nach Jahr.
• Mehr als drei Ebenen brauchst du selten. Die Volltextsuche in Paperless ersetzt tiefe Ordner.
• Tags bleiben für alles, was sich mit Ordnern nicht abbilden lässt, etwa “Frist prüfen” oder “Steuer absetzbar”.

Typische Fehler

Dokumente werden als fehlend gemeldet. Du hast Dateien von Hand verschoben. Stelle das Backup wieder her oder führe sudo docker compose exec paperless document_sanity_checker aus, um die Liste der betroffenen Dokumente zu sehen.

Der Pfad enthält none. Ein Platzhalter hat bei diesem Dokument keinen Wert. Weise Korrespondent oder Dokumenttyp zu oder aktiviere PAPERLESS_FILENAME_FORMAT_REMOVE_NONE.

Die Vorlage hat keine Wirkung. Bei einem Fehler in den Platzhaltern fällt Paperless auf 0000001.pdf zurück. Prüfe die Klammern und teste die Vorlage in der Vorschau eines Speicherpfads.

Alte Dokumente bleiben am alten Ort. Nach einer Änderung von PAPERLESS_FILENAME_FORMAT musst du document_renamer einmal ausführen. Änderungen an einem Speicherpfad greifen dagegen automatisch.

FAQ