Advanced topics — Paperless-ng 1.5.0 documentation (2024)

Paperless offers a couple features that automate certain tasks and make your lifeeasier.

Matching tags, correspondents and document types

Paperless will compare the matching algorithms defined by every tag andcorrespondent already set in your database to see if they apply to the text ina document. In other words, if you defined a tag called Home Utilitythat had a match property of bc hydro and a matching_algorithm ofliteral, Paperless will automatically tag your newly-consumed document withyour Home Utility tag so long as the text bc hydro appears in the bodyof the document somewhere.

The matching logic is quite powerful, and supports searching the text of yourdocument with different algorithms, and as such, some experimentation may benecessary to get things right.

In order to have a tag, correspondent or type assigned automatically to newlyconsumed documents, assign a match and matching algorithm using the webinterface. These settings define when to assign correspondents, tags and typesto documents.

The following algorithms are available:

  • Any: Looks for any occurrence of any word provided in match in the PDF.If you define the match as Bank1 Bank2, it will match documents containingeither of these terms.

  • All: Requires that every word provided appears in the PDF, albeit not in theorder provided.

  • Literal: Matches only if the match appears exactly as provided in the PDF.

  • Regular expression: Parses the match as a regular expression and tries tofind a match within the document.

  • Fuzzy match: I dont know. Look at the source.

  • Auto: Tries to automatically match new documents. This does not require youto set a match. See the notes below.

When using the “any” or “all” matching algorithms, you can search for termsthat consist of multiple words by enclosing them in double quotes. For example,defining a match text of "Bank of America" BofA using the “any” algorithm,will match documents that contain either “Bank of America” or “BofA”, but willnot match documents containing “Bank of South America”.

Then just save your tag/correspondent and run another document through theconsumer. Once complete, you should see the newly-created document,automatically tagged with the appropriate data.

Automatic matching

Paperless-ng comes with a new matching algorithm called Auto. This matchingalgorithm tries to assign tags, correspondents and document types to yourdocuments based on how you have assigned these on existing documents. Ituses a neural network under the hood.

If, for example, all your bank statements of your account 123 at the Bank ofAmerica are tagged with the tag “bofa_123” and the matching algorithm of thistag is set to Auto, this neural network will examine your documents andautomatically learn when to assign this tag.

Paperless tries to hide much of the involved complexity with this approach.However, there are a couple caveats you need to keep in mind when using thisfeature:

  • Changes to your documents are not immediately reflected by the matchingalgorithm. The neural network needs to be trained on your documents afterchanges. Paperless periodically (default: once each hour) checks for changesand does this automatically for you.

  • The Auto matching algorithm only takes documents into account which are NOTplaced in your inbox (i.e., have inbox tags assigned to them). This ensuresthat the neural network only learns from documents which you have correctlytagged before.

  • The matching algorithm can only work if there is a correlation between thetag, correspondent or document type and the document itself. Your bankstatements usually contain your bank account number and the name of the bank,so this works reasonably well, However, tags such as “TODO” cannot beautomatically assigned.

  • The matching algorithm needs a reasonable number of documents to identify whento assign tags, correspondents, and types. If one out of a thousand documentshas the correspondent “Very obscure web shop I bought something five yearsago”, it will probably not assign this correspondent automatically if you buysomething from them again. The more documents, the better.

  • Paperless also needs a reasonable amount of negative examples to decide whennot to assign a certain tag, correspondent or type. This will usually be thecase as you start filling up paperless with documents. Example: If all yourdocuments are either from “Webshop” and “Bank”, paperless will assign one ofthese correspondents to ANY new document, if both are set to automatic matching.

Hooking into the consumption process

Sometimes you may want to do something arbitrary whenever a document isconsumed. Rather than try to predict what you may want to do, Paperless letsyou execute scripts of your own choosing just before or after a document isconsumed using a couple simple hooks.

Just write a script, put it somewhere that Paperless can read & execute, andthen put the path to that script in paperless.conf with the variable nameof either PAPERLESS_PRE_CONSUME_SCRIPT orPAPERLESS_POST_CONSUME_SCRIPT.


These scripts are executed in a blocking process, which means that ifa script takes a long time to run, it can significantly slow down yourdocument consumption flow. If you want things to run asynchronously,you’ll have to fork the process in your script and exit.

Pre-consumption script

Executed after the consumer sees a new document in the consumption folder, butbefore any processing of the document is performed. This script receives exactlyone argument:

  • Document file name

A simple but common example for this would be creating a simple script likethis:


#!/usr/bin/env -i ${1}



This will pass the path to the document about to be consumed to /usr/local/bin/ocr-pdf,which will in turn call on your document, which will thenoverwrite the file with an OCR’d version of the file and exit. At which point,the consumption process will begin with the newly modified file.

Post-consumption script

Executed after the consumer has successfully processed a document and has moved itinto paperless. It receives the following arguments:

The script can be in any language you like, but for a simple shell scriptexample, you can take a look at in thescripts directory in this project.

The post consumption script cannot cancel the consumption process.

File name handling

By default, paperless stores your documents in the media directory and renames themusing the identifier which it has assigned to each document. You will end up gettingfiles like 0000123.pdf in your media directory. This isn’t necessarily a badthing, because you normally don’t have to access these files manually. However, ifyou wish to name your files differently, you can do that by adjusting thePAPERLESS_FILENAME_FORMAT configuration option.

This variable allows you to configure the filename (folders are allowed) usingplaceholders. For example, configuring this to


will create a directory structure as follows:

2019/ My bank/ Statement January.pdf Statement February.pdf2020/ My bank/ Statement January.pdf Letter.pdf Letter_01.pdf Shoe store/ My new shoes.pdf


Do not manually move your files in the media folder. Paperless remembers thelast filename a document was stored as. If you do rename a file, paperless willreport your files as missing and won’t be able to find them.

Paperless provides the following placeholders withing filenames:

  • {asn}: The archive serial number of the document, or “none”.

  • {correspondent}: The name of the correspondent, or “none”.

  • {document_type}: The name of the document type, or “none”.

  • {tag_list}: A comma separated list of all tags assigned to the document.

  • {title}: The title of the document.

  • {created}: The full date and time the document was created.

  • {created_year}: Year created only.

  • {created_month}: Month created only (number 1-12).

  • {created_day}: Day created only (number 1-31).

  • {added}: The full date and time the document was added to paperless.

  • {added_year}: Year added only.

  • {added_month}: Month added only (number 1-12).

  • {added_day}: Day added only (number 1-31).

Paperless will try to conserve the information from your database as much as possible.However, some characters that you can use in document titles and correspondent names (suchas : \ / and a couple more) are not allowed in filenames and will be replaced with dashes.

If paperless detects that two documents share the same filename, paperless will automaticallyappend _01, _02, etc to the filename. This happens if all the placeholders in a filenameevaluate to the same value.


Paperless checks the filename of a document whenever it is saved. Therefore,you need to update the filenames of your documents and move them after alteringthis setting by invoking the document renamer.


Make absolutely sure you get the spelling of the placeholders right, or elsepaperless will use the default naming scheme instead.


As of now, you could totally tell paperless to store your files anywhere outsidethe media directory by setting


However, keep in mind that inside docker, if files get stored outside of thepredefined volumes, they will be lost after a restart of paperless.

Advanced topics — Paperless-ng 1.5.0 documentation (2024)


What is the difference between Papermerge and paperless-NGX? ›

What's the difference between Papermerge and Paperless-ng/Paperless-ngx? They are similar in many aspects. Compared to Papermerge, Paperless-ngx follows minimalist approach. Papermerge offers more complex features like multi-user, folder structure, document versioning, page management (split, merge, delete, rotate).

What is paperless ng? ›

Paperless-ngx is a community-supported open-source document management system that transforms your physical documents into a searchable online archive so you can keep, well, less paper.

Where does store files? ›

The persistent storage of Paperless is located at /var/lib/paperless and contains the media folder, the data folder (by default containing the SQLite database), the consume folder for document consumption, the temporary uploads folder and tmp convert folder.

How to install paperless on Docker? ›

  1. Use the easy install docker script.
  2. Pull the image from Docker Hub.
  3. Build the Docker image yourself.
  4. Install Paperless directly on your system manually (bare metal)
  5. A user-maintained list of commercial hosting providers can be found in the wiki.

Why is going paperless a bad idea? ›

These situations highlight one of the biggest disadvantages of going paperless; without a printed backup of your files, your business operations will be put on hold. This is why keeping physical copies of documents is vital to ensure that you always have access to important data if technology ever decides to fail you.

What are the pros and cons of going paperless? ›

Paperless Office Advantages... And Disadvantages
  • Advantage: Save Money and Space.
  • Disadvantage: Resources are Needed for IT Management and Training.
  • Advantage: Boost your Security.
  • Disadvantage: There's Still the Potential for Cyber Attacks.
  • Advantage: Improve Document Organization and Accessibility.
Feb 14, 2023

What is an example of paperless? ›

Email or instant messaging: Instead of using print correspondence, a paperless option is to move all communications to email or another instant messaging platform. For example, email promotions to your clients and use an instant messaging platform to make internal communications more efficient.

What are the benefits of paperless-NGX? ›

Paperless-ngx features & resources

Performs OCR on your documents, adds selectable text to image only documents and adds tags, correspondents and document types to your documents. Paperless stores your documents plain on disk. Filenames and folders are managed by paperless and their format can be configured freely.

What does fully paperless mean? ›

Paperless is a term used to describe office environments with complete digital documentation, record keeping and filing systems. In a paperless office, computer systems are used to create, store, retrieve, and dispose of documents and records.

Where does paperless save documents? ›

By default, paperless stores your documents in the media directory and renames them using the identifier which it has assigned to each document. You will end up getting files like 0000123. pdf in your media directory.

What is the username of paperless ng? ›

Default login is admin:admin via the webui, accessible at http://SERVERIP:PORT More info at paperless-ng.

How do I go paperless with documents? ›

You can start going paperless by embracing technology. Start new good habits by not printing out documents and using an electronic signature tool like DocuSign eSignature to get documents signed online. Start storing your documents in the cloud using Microsoft OneDrive, Google Drive or Dropbox.

How do you create a user in paperless? ›

To add a user in Paperless Pipeline: Go to Admin / Settings by clicking your name in the upper right corner, then [Admin / Settings]. Click [Manage Users]. Click [Add User].

What is the default port for paperless? ›

Adjust port if necessary. Default is 5432. Database name in PostgreSQL. Defaults to "paperless".

What is the admin password for paperless-NGX? ›

Default login is admin:admin via the webui, accessible at http://SERVERIP:PORT More info at paperless-ngx.

What is the difference between paperless and paper? ›

A paperless filing system is simply an electronic system used for storing documents. It can increase your productivity, reduce expenses, and eliminate the need for storage space. It is simple to implement, easy to adapt to, and relatively inexpensive. We refer to this as the “Less Paper” Office.

What formats are paperless-NGX? ›

What file types does paperless-ngx support?
  • PDF documents, PNG images, JPEG images, TIFF images, GIF images and WebP images are processed with OCR and converted into PDF documents.
  • Plain text documents are supported as well and are added verbatim to paperless.

What is the best device for going paperless? ›

A robust physical scanner is an excellent investment if you're serious about being paperless. The document scanner will not only help scan your papers but, with proper software and planning, will efficiently organize your new digital files plus allows you to automate your data input processes too.

What is the point of going paperless? ›

Going paperless can save money in several ways by reducing the need for paper, ink, and equipment. Reducing the use of paper can save money on the cost of buying paper, as well as the cost of disposing of it. Businesses can also save money on mailing and shipping costs by transmitting digital documents electronically.

Top Articles
Latest Posts
Article information

Author: Golda Nolan II

Last Updated:

Views: 5536

Rating: 4.8 / 5 (58 voted)

Reviews: 81% of readers found this page helpful

Author information

Name: Golda Nolan II

Birthday: 1998-05-14

Address: Suite 369 9754 Roberts Pines, West Benitaburgh, NM 69180-7958

Phone: +522993866487

Job: Sales Executive

Hobby: Worldbuilding, Shopping, Quilting, Cooking, Homebrewing, Leather crafting, Pet

Introduction: My name is Golda Nolan II, I am a thoughtful, clever, cute, jolly, brave, powerful, splendid person who loves writing and wants to share my knowledge and understanding with you.