Paperless Storage Path: How to Make Paperless-ngx File Documents Into Folders You Can Browse
A storage path in Paperless-ngx is a named filename template that decides where a document’s files are written on disk and what they are called. Without one, Paperless saves files by their database ID, such as 0000123.pdf, in the media directory. With a storage path like {{ created_year }}/{{ correspondent }}/{{ title }}, the same document lands in 2026/My bank/Statement October.pdf. You create storage paths in the web UI, assign them to documents by hand or with the same matching rules used for tags, and Paperless moves the files whenever the path or the document’s metadata changes.
That last point is what makes storage paths useful and what makes careless edits risky. This guide covers how storage paths relate to the global filename setting, which placeholders and template features you can use, how to assign paths automatically, and how to change a layout on an archive that already holds thousands of documents.
Storage paths and PAPERLESS_FILENAME_FORMAT
Paperless has two layers of file naming, documented together under file name handling:
PAPERLESS_FILENAME_FORMATis a single, instance-wide template set as an environment variable. Its default is empty, which gives you the numeric filenames.- A storage path is one more template of the same kind, stored in the database and attached to individual documents.
A document with a storage path uses that path. A document without one falls back to the global format. So a common setup is a sensible global format for everything, plus a few storage paths for document groups that need their own structure.
The two layers behave differently when you change them. Editing or deleting a storage path is applied to the file system automatically, because Paperless checks a document’s filename every time the document is saved. Changing PAPERLESS_FILENAME_FORMAT does nothing to existing files until you run the document_renamer management command. In both cases Paperless renames files inside its media directory, which keeps originals and the generated archive PDFs in separate folders, and it adds the file extension itself, so templates never end in .pdf.
Placeholders you can use
The basic building blocks are placeholders in double curly braces. The most useful ones:
| Placeholder | Value |
|---|---|
{{ title }} |
Document title |
{{ correspondent }} |
Correspondent name, or none |
{{ document_type }} |
Document type name, or none |
{{ created }} |
Created date in ISO format, e.g. 2026-03-14 |
{{ created_year }}, {{ created_month }}, {{ created_day }} |
Parts of the created date |
{{ created_month_name }} |
Month name in the server locale |
{{ added }}, {{ added_year }} |
Date the document entered Paperless |
{{ asn }} |
Archive serial number, or none |
{{ owner_username }} |
Owner’s username, or none |
{{ original_name }} |
Original filename without extension |
{{ doc_pk }} |
Internal document ID |
{{ tag_list }} |
Comma-separated tag names |
A few rules follow from the documentation and save confusion later:
- Characters that are not allowed in filenames, such as
/,\and:, are replaced with dashes. A correspondent calledACME/Billingbecomes the folderACME-Billing. - If two documents resolve to the same name, Paperless appends
_01,_02, and so on. - Empty values become the literal folder
none. SetPAPERLESS_FILENAME_FORMAT_REMOVE_NONE=trueto drop them instead. {{ tag_list }}can produce very long paths. If a path exceeds the operating system limit, the file keeps its previous name and the problem is logged.- Use
{{ created }}rather than{{ added }}for anything a person will browse. The created date is the date printed on the document; the added date is when you happened to scan it.
Templates worth copying
The documentation’s own example is a good starting point: two storage paths, one for general mail and one for insurance correspondence.
By Year = {{ created_year }}/{{ correspondent }}/{{ title }}
Insurances = Insurances/{{ correspondent }}/{{ created_year }}-{{ created_month }}-{{ created_day }} {{ title }}
Some variations that solve common problems:
A flat folder per document type, with dates first so files sort chronologically in any file browser:
{{ document_type }}/{{ created }} {{ correspondent }} {{ title }}
Files grouped by physical binder, useful if you keep originals numbered by ASN:
Binders/ASN {{ asn }} {{ title }}
Separate trees for each household member or team, combined with ownership set by a workflow:
{{ owner_username }}/{{ created_year }}/{{ document_type }}/{{ title }}
Keep folder levels to two or three. Every extra level is another value that can be wrong or missing, and a wrong correspondent at the first level puts the file in the wrong place entirely.
Jinja logic and custom fields
Storage path templates are rendered with Jinja, so you can use conditions and filters. The template may span several lines; Paperless joins it into a single path. A limited document object is also available, with fields such as document.mime_type, document.page_count and document.archive_serial_number.
Custom fields are where this becomes practical. Paperless provides a get_cf_value filter that reads a field by name and accepts a default, plus a datetime filter for formatting dates. This path files invoices by the invoice date and number stored in custom fields, rather than by the scan date:
Invoices/
{{ custom_fields | get_cf_value("Invoice Date", "0000-01-01") | datetime("%Y") }}/
{{ correspondent }} {{ custom_fields | get_cf_value("Invoice Number", "no-number") }}
The defaults matter. Without them, a document that has not had its custom fields filled in yet produces an incomplete path. With them, it lands in an obvious 0000 folder that you can review. Use get_cf_value for any field name containing a space; dot access like custom_fields.Invoice.value only works for single-word names. There is also a slugify filter if you want lowercase, hyphenated filenames: {{ title | slugify }}.
The full list of filters, with examples for ASN ranges and file types, is in the filename templates section of the docs.
Assigning storage paths automatically
A storage path has a match field and a matching algorithm, the same options you see on tags and correspondents: Any, All, Exact, Regular expression, Fuzzy, Auto, or None. The matching documentation explains each. For storage paths, Exact or Regular expression on a phrase that only appears on the right documents is the predictable choice. Auto uses the trained classifier and needs a reasonable number of correctly filed documents before it helps.
Matching on text works when the documents say something distinctive. When the right folder depends on metadata instead, workflows are clearer. An Assignment action can set the storage path, and a Document Added trigger can filter on document type, correspondent, tags or custom field values that were set earlier in processing. For example: when the document type is Invoice, assign the storage path Invoices. A Consumption Started trigger with a file path filter can do the same based on which consume subfolder a scan arrived in.
Workflow assignments run in sort order, and a later assignment of a single-value field such as storage path overrides an earlier one. If a document keeps ending up in the wrong path, check the workflow order before rewriting the template. Our Paperless-ngx tips article covers workflow triggers and matching in more depth.
To check where documents currently sit, use the document list filter or search with path: (or storage_path:), for example path:Invoices.
Changing a layout on an existing archive
Paperless will move files for you, but a layout change on a large archive is still an operation worth planning:
-
Back up first. Run
document_exporterand make sure the export is copied somewhere other than the Paperless host. The paperless archive guide explains why a backup you have restored is worth more than one you have only created. -
Test the template. The storage path edit dialog has a live preview: pick an existing document and it shows the path that document would get. Try a document with no correspondent, one with a long title, and one without the custom fields the template uses.
-
Apply it. For an existing storage path, saving the new template triggers the moves. For new paths that should apply to old documents, run the retagger with the storage path option so matching rules are evaluated again:
docker compose exec webserver document_retagger -sAs with correspondents and document types, it does not replace values that are already assigned unless you ask it to. Add
-fto overwrite them, and--id-range 1 100to try the rule on a small set first. -
If you changed
PAPERLESS_FILENAME_FORMAT, recreate the container withdocker compose up -dso the new value is loaded, then rundocker compose exec webserver document_renamer. -
Check the result with
document_sanity_checker, which reports missing files and orphaned files in the media directory.
Two things to avoid. Do not rename or move files in the media folder by hand: Paperless stores the last filename it used for each document and will report hand-moved files as missing. And do not point a template outside the media directory with ../. The docs note it is technically possible, but in Docker anything written outside the mounted volumes is lost when the container is recreated.
What storage paths do not do
Storage paths organize files on disk. They do not change what you see in the Paperless web UI, where tags, document types and saved views remain the way to browse. They also do not make metadata correct: a template built on correspondent and created date files a misread document confidently into the wrong folder. Paperless reads the created date from the OCR text, and when the OCR is poor or a page carries several dates, it can pick the wrong one.
That is the limit worth planning around. The better the metadata, the more a storage path layout is worth, which is why OCRskill focuses on that step. Connected to Paperless through a workflow webhook, it reads each new page with a vision model and returns the document type, correspondent and issue date for Paperless to store, so the storage path has the right values to work with. The setup is described in our Paperless-ngx archive tutorial.
Conclusion
A Paperless storage path is a per-document filename template that overrides the global PAPERLESS_FILENAME_FORMAT. Start with one simple layout based on created year and correspondent, add separate paths only for document groups that need a different structure, and use custom fields with get_cf_value defaults when the folder should depend on values printed on the document. Preview every template on awkward documents, back up before changing a layout on an existing archive, and let Paperless move the files rather than moving them yourself.
