Paperless-ngx User Guide

Paperless-ngx is a self-hosted document management system. You feed it your scanned paper, PDFs, and office files; it runs OCR, makes everything full-text searchable, and lets you organize documents with tags, correspondents, document types, and storage paths — automatically. This guide walks you through getting Paperless-ngx running and using it day to day: importing documents, finding them again, keeping them organized, and automating the repetitive parts.

Note

Paperless-ngx is a web application. Once it is running you interact with it through your browser at the address of your server (for example http://localhost:8000). There is no desktop app to install, though a mobile companion app and third-party clients exist that talk to the same REST API.

1. Quick Start

The fastest way to a working instance is Docker Compose. You need Docker and the Docker Compose plugin installed.

The project ships an interactive installer that downloads the right Compose file, generates a secret key, and creates your first user.

Interactive installer (recommended)

bash -c "$(wget -q https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh -O -)"

The script asks you a series of questions (URL, port, time zone, database backend, OCR language, admin username and password) and then starts everything for you.

Manual Compose

# 1. Create a project folder
mkdir paperless-ngx && cd paperless-ngx

# 2. Download a compose file (PostgreSQL shown here) and env templates
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml -O docker-compose.yml
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env -O .env

# 3. Pull images and start
docker compose pull
docker compose up -d

# 4. Create your first user
docker compose run --rm webserver createsuperuser

After the containers start, open your browser:

http://localhost:8000

Log in with the user you created. You will land on the dashboard.

Tip

Drop a PDF into the consume folder (mounted at ./consume in the Compose files) or use the upload button in the web interface. Within a few seconds Paperless-ngx OCRs it, files it, and it appears in your document list — searchable by its text content.

Important

The default Compose stack listens on port 8000. The Portainer variant uses 8010. If that port is taken, change the left-hand side of the ports: mapping (for example "8001:8000").

2. Installation

Paperless-ngx is built and tested to run in Docker. It consists of several cooperating services, all defined for you in the official Compose files.

2.1 Requirements

The official image bundles everything the application needs at runtime — Python, Tesseract OCR, Ghostscript, ImageMagick, and the web server. You do not install those yourself when using Docker.

2.2 Choosing a Compose file

The project provides several ready-made Compose files under docker/compose/. Pick one based on your database choice and whether you need Office-document support (Tika/Gotenberg).

Tip

Use PostgreSQL if you are unsure. On a low-power device such as a Raspberry Pi, SQLite saves resources. Choose a -tika variant only if you want to import Word, Excel, PowerPoint, or LibreOffice documents — it adds the Apache Tika and Gotenberg containers.

Every Compose stack starts the same core services:

webserver   the Paperless-ngx application (port 8000)
broker      Redis — the task queue and channel layer
db          PostgreSQL or MariaDB (omitted for SQLite stacks)
gotenberg   only in -tika stacks: renders Office docs / .eml to PDF
tika        only in -tika stacks: extracts text from Office docs

2.3 First-run setup

After docker compose up -d, create an administrator account:

docker compose run --rm webserver createsuperuser

Username: admin
Email address: [email removed]
Password: ********
Superuser created successfully.

You can also have the first user created automatically by setting PAPERLESS_ADMIN_USER and PAPERLESS_ADMIN_PASSWORD in your environment before the first start (see the Admin Guide for details).

Warning

Paperless-ngx refuses to start unless PAPERLESS_SECRET_KEY is set to a real, unique value. The default change-me is rejected. The interactive installer generates one for you; if you write your own Compose file, generate a key with:

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

2.4 Updating

cd paperless-ngx
docker compose pull
docker compose up -d

Database migrations run automatically on startup. Always back up first (see Backups).

3. The Consume Folder and Uploading

Getting documents into Paperless-ngx is the heart of the system. There are several ways to do it, and they all feed the same processing pipeline: OCR → text extraction → archive copy (PDF/A) → classification → indexing.

3.1 The consume folder

The consume folder is a directory Paperless-ngx watches. Anything you drop in is picked up and imported automatically. In the Compose files it is mounted at ./consume on the host.

paperless-ngx/
└── consume/          ← drop files here
    ├── invoice.pdf
    └── receipts/
        └── coffee.jpg

Point your scanner, a network share, or a sync tool (Syncthing, Nextcloud) at this folder and documents flow in with no manual step.

Note

The watcher waits for a file to be stable before consuming it — its size and modification time must stop changing for a short delay. This prevents half-written files (slow network copies, scanners that write in chunks) from being imported prematurely.

Paperless-ngx automatically ignores common system clutter in the consume folder, including .DS_Store, Thumbs.db, desktop.ini, macOS resource forks (._*), and sync metadata directories such as .stfolder/.stversions (Syncthing), @eaDir (Synology), .Spotlight-V100, and .Trashes.

3.2 Supported file types

Out of the box Paperless-ngx consumes PDFs and common image formats (PNG, JPEG, TIFF, and more). With a -tika stack it additionally accepts Office documents (Word, Excel, PowerPoint and LibreOffice equivalents) and .eml email files, which are converted to PDF for storage.

3.3 Uploading through the web interface

You do not have to use the consume folder. In the web UI you can:

• Click the upload button (or the upload widget on the dashboard) and select files.
• Drag and drop files directly onto the document list.

Uploaded files go through the exact same pipeline as consume-folder files.

3.4 Folders as tags

If you enable the subdirectories-as-tags option, the folder structure under the consume directory becomes tags. A file dropped at consume/Taxes/2025/return.pdf is tagged Taxes and 2025 automatically.

Tip

This is a fast way to pre-sort a large backlog: arrange your scans into folders that mean something to you, drop the whole tree into the consume folder, and let Paperless-ngx tag them as it imports.

3.5 Barcode splitting and ASNs

For high-volume scanning, Paperless-ngx can read barcodes on your pages to:

• Split one large scan into multiple documents at separator pages (a PATCHT patch-code barcode by default).
• Assign an Archive Serial Number (ASN) from a barcode, linking the digital document to a numbered physical file in a real-world archive.
• Apply tags from barcodes, and collate double-sided scans from a duplex feeder.

These are configured by the administrator; see the Admin Guide.

4. Organizing Your Documents

Paperless-ngx organizes documents with four kinds of metadata plus tags. Understanding them is the key to a tidy archive.

4.1 Correspondents, document types, and storage paths

Each document has at most one correspondent, one document type, and one storage path. You set them manually when reviewing a document, or let Paperless-ngx assign them automatically (see Automatic matching).

4.2 Tags

Tags are flexible labels. A document can carry any number of them, each with its own color. Tags can be nested (organized into a hierarchy up to five levels deep), which is handy for grouping related labels under a parent.

One special tag type is the inbox tag: any tag marked as an inbox tag is automatically applied to every newly consumed document. The dashboard shows how many documents still carry an inbox tag, giving you a natural "to review" queue.

Tip

Create a tag called Inbox and mark it as an inbox tag. New documents land there; remove the tag once you have reviewed and filed each one. Your inbox count tells you how much is left to triage.

4.3 Custom fields

When the built-in metadata is not enough, define custom fields with specific data types — text, numbers, dates, monetary amounts, boolean, URL, document links, and select lists. For example, add an Amount money field to your invoices, then filter and sort by it.

4.4 Notes

You can attach free-text notes to any document — a comment thread for context that does not belong in the document's content itself.

5. Automatic Matching and Classification

Filing every document by hand is tedious. Paperless-ngx can assign correspondents, document types, tags, and storage paths for you, using two complementary mechanisms.

5.1 Matching algorithms

Every correspondent, document type, tag, and storage path has a matching algorithm and a match pattern. When a document is consumed (or when you re-run tagging), Paperless-ngx checks the document's text against these rules and assigns matches.

Matching can be made case sensitive or insensitive per item.

Note

"Exact match" looks for the match string anywhere in the document text, not a whole-document equality. For example, a correspondent with an exact match of City Power matches any document whose text contains that phrase.

5.2 The machine-learning classifier

When you set an item's algorithm to Automatic, Paperless-ngx learns from the documents you have already filed. A classifier is trained on your existing correspondents, types, tags, and storage paths, and then predicts metadata for new documents.

The classifier retrains itself automatically on a schedule (by default hourly), so it improves as you file more documents. You can also retrain it on demand — see Command-line tasks.

Tip

Start by filing a few documents of each kind manually. Once Paperless-ngx has examples to learn from, switch your common tags and types to Automatic and let the classifier take over.

5.3 Optional AI features

Paperless-ngx includes an opt-in AI layer that can use a Large Language Model (LLM) to suggest document metadata and to answer questions about your documents in a chat interface. It supports Ollama (local models) and OpenAI-compatible endpoints. This is disabled by default and configured by the administrator.

6. Finding Documents

Every document's text is indexed for full-text search, so you can find anything by what is inside it, not just its title.

6.1 Full-text search

Type into the search box at the top of the interface. Paperless-ngx searches the OCR'd content of all your documents and ranks results by relevance. Search is language-aware: it understands word stems, so searching invoices also finds invoice.

6.2 Filtering

The document list can be filtered by any combination of:

• Correspondent, document type, storage path
• Tags (including "has any of" / "has all of")
• Created, added, and modified dates (ranges)
• Custom field values
• Archive serial number

6.3 Saved views

Once you have built a useful filter, save it as a saved view. Saved views can be pinned to the sidebar and shown as widgets on your dashboard, giving you one-click access to, say, "Unpaid invoices" or "This year's tax documents."

Tip

Combine an inbox tag filter with a saved view called To review and pin it to your dashboard. It becomes your daily processing list.

6.4 Suggested dates

When you open a document, Paperless-ngx scans its text for dates and suggests them for the document's created date, so you rarely have to type it in manually.

7. Workflows: Automating the Repetitive Parts

Workflows let you run actions automatically when something happens to a document. A workflow has one or more triggers (when it runs) and one or more actions (what it does).

7.1 Triggers

A workflow can fire on events such as:

• A document is consumed (added to Paperless-ngx)
• A document is added or updated
• A document is scheduled (time-based, e.g. 60 days after the document date)

Triggers can be filtered so they only apply to documents matching certain conditions (source, file name, correspondent, type, tags, and more).

7.2 Actions

When a workflow's trigger fires, it can:

Tip

A classic workflow: trigger on consumption of any document whose text contains "invoice", action assign the Invoice document type and an Unpaid tag. New invoices file and flag themselves.

7.3 Scheduled workflows

Scheduled triggers run on a recurring check (hourly by default) and act on documents relative to a date field. For example, "90 days after a contract's created date, email me a reminder." This turns Paperless-ngx into a lightweight document-driven reminder system.

8. Command-line Tasks

Most day-to-day work happens in the browser, but several operations are available as management commands. With Docker, run them through the webserver container:

docker compose run --rm webserver <command> [options]

Commands that process many documents support a progress bar (disable it with --no-progress-bar) and some support parallelism with --processes N.

Tip

Run document_retagger --suggest after you create or change matching rules. It shows what would change so you can sanity-check before committing with a real run.

Caution

document_fuzzy_match --delete permanently deletes documents it considers duplicates. Run it without --delete first to review the matches.

9. Backing Up Your Data

The supported, portable way to back up Paperless-ngx is the document exporter. It writes every document, its metadata, and a manifest.json to a target directory in a format you can re-import on any instance.

docker compose run --rm webserver document_exporter ../export

Useful options:

Restore with the importer:

docker compose run --rm webserver document_importer ../export

Important

A plain copy of the Docker volumes is not a substitute for document_exporter across version upgrades. The exporter produces a database-independent, version-portable backup. Schedule it regularly.

Warning

If you have mail accounts or social logins configured and you do not pass --passphrase, their secrets are written to the export in plain text. Use a passphrase to encrypt them.

10. Sharing Documents

Paperless-ngx can generate share links — URLs that let someone view a specific document without a Paperless-ngx account. Share links can be set to expire after a chosen time. You can also bundle several documents into a single share. This is convenient for handing a document to an accountant or a colleague without giving them access to your archive.

Caution

Anyone with a share link can view the linked document until it expires. Set an expiry and treat the link as a secret.

11. Users, Permissions, and Login

If more than one person uses your instance, Paperless-ngx supports multiple users and groups. Documents and other objects have an owner and fine-grained view/edit permissions, so each user sees only what they should.

Sign-in options include a standard username/password login, multi-factor authentication (TOTP authenticator apps), and — when your administrator configures it — single sign-on through external identity providers (social/OIDC). An optional auto-login mode exists for trusted single-user setups.

Note

The very first user you create with createsuperuser is an administrator with full access, including the Django admin back office. Create additional, less-privileged users for everyday use where appropriate.

12. Troubleshooting

Error: PAPERLESS_SECRET_KEY is not set or is the default 'change-me' value

Cause: The application will not start without a unique secret key. Solution: Generate one and set it in your environment:

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

Put the result in PAPERLESS_SECRET_KEY (in docker-compose.env or your .env) and restart. Prevention: Use the interactive installer, which generates the key automatically.

A file I dropped in the consume folder was not imported

Cause: The file type is unsupported, it matched an ignore pattern, or it was still being written. Solution: Confirm the extension is supported (Office formats require a -tika stack). Check that the name is not something like .DS_Store or inside an ignored directory (.stfolder, @eaDir, etc.). Make sure the copy finished — the watcher waits for the file to stop changing before importing. Prevention: Copy files in atomically (write to a temp name, then rename) when scripting.

Office documents (Word/Excel) are rejected

Cause: Tika/Gotenberg are not running. The base stack handles PDFs and images only. Solution: Switch to a -tika Compose file so the tika and gotenberg containers start.

Search returns nothing for a document I can see

Cause: The search index is out of date or was not built. Solution: Rebuild it:

docker compose run --rm webserver document_index reindex

Dates on my documents are off by a day

Cause: The server's time zone is not set correctly. Solution: Set PAPERLESS_TIME_ZONE to your local zone (for example Europe/Berlin) and restart. The interactive installer asks for this.

OCR produces poor or wrong-language text

Cause: The OCR language does not match the document. Solution: Set PAPERLESS_OCR_LANGUAGE to the correct ISO 639-2 code (e.g. deu, fra), or a combination like deu+eng. The matching language data must be available in the image.

Auto-matching is not assigning tags or types

Cause: The classifier has not been trained, or items are not set to a matching algorithm. Solution: File a few documents manually first, set items to Automatic (or a word/regex match), then train:

docker compose run --rm webserver document_create_classifier

Known beta issues

Some features were reported as buggy in recent beta builds, including the Tasks UI filtering, the built-in PDF viewer/editor, and the AI chat display. If you hit one of these on a beta release, check the project's issue tracker for the current status before assuming a misconfiguration.

13. Frequently Asked Questions

Q: Do I need an internet connection to use Paperless-ngx? No. It is fully self-hosted and runs entirely on your own server. OCR, search, and classification all happen locally. (The optional AI features can call an external LLM if you choose to enable them.)

Q: Does Paperless-ngx modify or delete my original files? Your original is stored and kept. Paperless-ngx additionally generates an archive copy (a searchable PDF/A) and a thumbnail. Documents you delete go to a trash that is emptied on a delay, so accidental deletions can be recovered for a while.

Q: Which database should I choose? PostgreSQL is the recommended default. SQLite is fine for small or low-power setups. MariaDB is also supported. You choose this at install time via the Compose file.

Q: Can I import Word and Excel files? Yes, if you run a -tika Compose stack. Tika and Gotenberg convert Office and .eml files to PDF for storage and OCR.

Q: How do I move my archive to a new server? Use document_exporter on the old server and document_importer on the new one. The export is portable across versions and databases.

Q: Can Paperless-ngx pull documents from my email? Yes. It can connect to IMAP mail accounts and consume attachments according to mail rules you define, including via Gmail and Outlook OAuth. Your administrator sets this up.

Q: What is an Archive Serial Number (ASN)? A unique number you assign to a document that corresponds to where you filed the physical paper. It lets you go from the digital record back to the paper original. ASNs can be assigned automatically from barcodes.

Q: How do I assign tags based on folder structure? Enable the subdirectories-as-tags consumer option, then organize files into folders inside the consume directory. Each folder name becomes a tag.

Q: Can I run automatic actions when a document arrives? Yes — use Workflows. A trigger (e.g. "document consumed") runs actions (assign tags, set type, send email, call a webhook). Scheduled triggers can also act on a date relative to the document.

Q: Is there an API? Yes. Paperless-ngx exposes a full REST API, which is what the web interface and mobile/third-party apps use. See the Admin Guide and the project's API documentation.

Q: How many documents can it handle? Paperless-ngx is used with archives ranging from a handful to hundreds of thousands of documents. PostgreSQL and adequate disk are recommended for large collections.