All Guides

Install Paperless-ngx: Self-Host a Paperless Office 2026

Guide: install Paperless-ngx with Docker Compose, set the OCR language, import documents via the consume folder and email, back up with the document exporter.

Dirk Hesse
January 22, 2026
12 min read

The shoebox full of invoices. The folders you haven't opened in years. The important document you searched for last week.

Paper chaos costs time and nerves. Cloud services store your contracts and bank statements on someone else's servers; who can access them is set by their terms.

On your own VPS (virtual private server, a virtual server in a data center), Paperless-ngx runs with OCR, automatic matching and full-text search. Current prices are in the VPS comparison, sorted by price.

Prerequisites

You need:

Providers at a glance: Hetzner, Netcup; all plans in the VPS comparison.

Not sure yet whether to install Paperless on your NAS or a VPS? Our NAS vs VPS comparison helps you decide.

Looking for a server for Paperless?

The Paperless calculator estimates how much RAM and storage your archive needs.

Open Paperless calculator

Paperless-ngx hosting: matching VPS plans

The cheapest plans with at least 4 GB RAM, 2 vCPU and 40 GB storage, sorted by price. For Paperless-ngx these are the defaults of our calculator.

Prices incl. VAT · Prices as of Nov 18, 2026 · How we rank (methodology)

Compare all 60 matching plans →

Step 1: Install Paperless-ngx

We use Docker Compose with PostgreSQL. The files come from the project repository (Paperless-ngx repo, as of Nov 8, 2026); alternatively, the setup page offers an install script (Paperless-ngx docs, as of Nov 8, 2026).

mkdir -p ~/paperless && cd ~/paperless

Download the Compose file, env file and .env:

curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
mv docker-compose.postgres.yml docker-compose.yml
curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env
docker compose pull

The .env sets the project name paperless. Before the first start, replace the webserver port line "8000:8000" with "127.0.0.1:8000:8000": otherwise port 8000 is open on all interfaces, and Docker bypasses ufw (Docker docs, as of Nov 8, 2026). Adjust key settings in docker-compose.env:

nano docker-compose.env

# Set:
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
PAPERLESS_SECRET_KEY=paste-the-generated-value-here

PAPERLESS_OCR_LANGUAGE defaults to eng; English, German, Italian, Spanish and French are already in the Docker image (Paperless-ngx docs, as of Nov 8, 2026). Generate the secret key in the terminal with openssl rand -hex 32 and paste the output; env files don't run shell commands.


Step 2: Start and create an admin

Start the containers:

docker compose up -d

On first access to the web UI, Paperless asks you to create a superuser (Paperless-ngx docs, as of Nov 8, 2026). Alternatively, set PAPERLESS_ADMIN_USER and PAPERLESS_ADMIN_PASSWORD in the env file (Paperless-ngx docs, as of Nov 8, 2026).

This user is your admin account.


Step 3: First login

Port 8000 is the default (Paperless-ngx docs, as of Nov 8, 2026). Since the port is bound locally, reach it for initial setup via SSH tunnel: ssh -L 8000:127.0.0.1:8000 user@server, then http://localhost:8000 in the browser. Then HTTPS (step 8).

  1. Log in with your admin account
  2. Explore the dashboard
  3. Common OCR settings can also be set in the web UI and take precedence there over environment variables (Paperless-ngx docs, as of Nov 8, 2026)

Step 4: Understand the consume folder

The consume folder is the heart of Paperless:

Paperless processes files you put into this folder automatically: OCR, indexing, matching. After processing, Paperless removes the file from the consume folder and stores it in its own storage; on multi-core systems several documents run in parallel (Paperless-ngx docs, as of Nov 8, 2026).

# Consume folder path (default)
~/paperless/consume/
# Or in the container: /usr/src/paperless/consume/

Example: add a document manually:

cp invoice-example.pdf ~/paperless/consume/
# After processing, the document appears in the web UI

Step 5: Set up a scanner

Several ways to get documents into the consume folder:

Option A: Smartphone app

For occasional scans:

  1. Install a scanner app that exports PDFs. The project wiki lists apps with a direct Paperless connection; they are third-party apps the Paperless team doesn't support (Paperless-ngx wiki, as of Nov 8, 2026)
  2. Photograph the document
  3. Export as PDF
  4. Upload to the server via SFTP

Option B: Network scanner

For regular scans:

  1. Configure the scanner for SFTP upload, if it supports it
  2. Target: ~/paperless/consume/
  3. Don't expose SMB or FTP to the internet; use them over a VPN

Option C: Email import

For digital invoices – see next section.


Step 6: Set up email import (optional)

You create mail accounts and mail rules in the web UI (Settings → Mail), not via environment variables (Paperless-ngx docs, as of Nov 8, 2026). SMTP variables such as PAPERLESS_EMAIL_HOST are for sending email, not fetching it.

By default, Paperless checks mail every ten minutes. Change the interval via PAPERLESS_EMAIL_TASK_CRON (Paperless-ngx docs, as of Nov 8, 2026), then restart the containers:

docker compose down && docker compose up -d

Your mail rules decide what gets imported.

Warning: Use a dedicated email account for Paperless, not your main address!


Step 7: Set up automatic matching

Automatic matching learns from documents you've already assigned:

1. Create correspondents

Under 'Manage' → 'Correspondents', add frequent senders (phone carrier, online shop, insurer)

2. Define document types

Under 'Document Types': invoice, contract, bank statement, tax, etc.

3. Create tags

For categories: 'Tax 2026', 'Important', 'Insurance', etc.

4. Define matching rules

For each correspondent, document type or tag, choose the "Auto" algorithm. Paperless then learns from your assignments; documents in the inbox don't count, and matching runs once an hour by default (Paperless-ngx docs, as of Nov 8, 2026).

Tip: Per the docs, matching needs enough assigned documents and counterexamples. The more, the more reliable (Paperless-ngx docs, as of Nov 8, 2026).


Step 8: Set up HTTPS (recommended)

For secure access from outside, put Caddy in front as a reverse proxy. Behind a reverse proxy, set PAPERLESS_URL=https://paperless.yourdomain.com (no trailing slash) in the env file (Paperless-ngx docs, as of Nov 8, 2026).

Extend docker-compose.yml:

services:
  # ... existing services (webserver port bound locally since step 1)

  caddy:
    image: caddy:2
    restart: always
    ports:
      - 80:80
      - 443:443
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data

# add to the existing volumes: block:
#   caddy_data:

Caddyfile:

paperless.yourdomain.com {
    reverse_proxy webserver:8000
}

Then restart with docker compose up -d. The local binding from step 1 and caddy_data in the existing volumes: block are RackDiff notes, not Paperless docs.


Step 9: Set up backups (important!)

Back up the media and data volumes and, with PostgreSQL, the database (Paperless-ngx docs, as of Nov 8, 2026). The built-in export is simplest; nothing should be processing at the time:

cd ~/paperless
docker compose exec -T webserver document_exporter ../export
# Output lands in the export folder next to the Compose file

Backup script:

#!/bin/bash
BACKUP_DIR="/backup/paperless"
DATE=$(date +%Y%m%d)
mkdir -p "$BACKUP_DIR"
cd ~/paperless

# Export documents and metadata
docker compose exec -T webserver document_exporter ../export

# PostgreSQL backup
docker compose exec -T db pg_dump -U paperless > "$BACKUP_DIR/db-$DATE.sql"

# Archive the export
tar -czf "$BACKUP_DIR/export-$DATE.tar.gz" export

# Delete old backups (30 days)
find "$BACKUP_DIR" -mtime +30 -delete

Warning: Try a restore at least once. A backup you've never restored is a risk. The archives sit unencrypted on the same server; encrypt them, e.g. with restic or borgbackup, and copy them to a second location.


Advanced: More configuration

Useful settings from the configuration page (Paperless-ngx docs, as of Nov 8, 2026):

SettingConfigDescription
Redo OCRPAPERLESS_OCR_MODE=redoOCR on all pages, existing text layers are replaced; force rasterizes pages
Archive formatPAPERLESS_OCR_OUTPUT_TYPE=pdfaDefault pdfa; the original is kept
Save storagePAPERLESS_ARCHIVE_FILE_GENERATION=neverStore only the original; preview shows the original file
More OCR languagesPAPERLESS_OCR_LANGUAGE=deu+eng+fraFrench is in the image, more via PAPERLESS_OCR_LANGUAGES
Barcode detectionPAPERLESS_CONSUMER_ENABLE_BARCODES=trueSplits documents at separator pages with a barcode (default PATCHT), off by default

Barcode splitting has its own page (Paperless-ngx docs, as of Nov 8, 2026).


Example workflow: tax return

One possible flow for your tax return:

  1. Create tag 'Tax 2026'
  2. Scan all relevant documents (donation receipts, invoices, etc.)
  3. If the tag uses "Auto" matching, Paperless can assign it to new documents; check the assignment before export (Paperless-ngx docs, as of Nov 8, 2026)
  4. At year end: filter 'Tag = Tax 2026'
  5. Export all documents or show them to your tax advisor
  6. When done: change the tag to 'Tax 2026 done'

Paperless doesn't change the original and creates an archive version for scanned documents (Paperless-ngx docs, as of Nov 8, 2026). Whether you may destroy paper originals after scanning depends on retention rules, for businesses in Germany e.g. § 147 AO (§ 147 AO, as of Nov 8, 2026). If in doubt, ask your tax advisor.


Optimize OCR & languages

Text recognition is the heart of Paperless-ngx and a major lever for compute time and accuracy. Paperless recognizes text with OCRmyPDF and Tesseract, controlled via environment variables in docker-compose.env (Paperless-ngx docs, as of Nov 8, 2026):

# Several OCR languages (German + English)
PAPERLESS_OCR_LANGUAGE=deu+eng
# Default: OCR only if the document has no text yet
PAPERLESS_OCR_MODE=auto
# Archive version format
PAPERLESS_OCR_OUTPUT_TYPE=pdfa

In the default auto mode, Paperless uses pdftotext to check whether a document already has text and then skips OCR, e.g. for invoices from online banking (Paperless-ngx docs, as of Nov 8, 2026). Install extra Tesseract languages via PAPERLESS_OCR_LANGUAGES.

Storage & maintenance

Paperless keeps the original and creates an archive version for scanned or image-based documents (Paperless-ngx docs, as of Nov 8, 2026). Storage needs depend on scan resolution, file type and archive version. The Paperless calculator gives an estimate; plans with more storage are in the VPS comparison, sorted by price.

For ongoing operation:


Multiple users & permissions

Once more than one person uses the archive, Paperless-ngx's user management pays off. Under Settings → Users & Groups you add users and groups; every object has an owner and view and edit permissions (Paperless-ngx docs, as of Nov 8, 2026).

This is handy for families or small teams. Documents have their own permissions and by default are visible only to their owner. Permissions on a tag don't change access to documents with that tag (Paperless-ngx docs, as of Nov 8, 2026).

Important: give every user their own account with a strong password. Each person enables two-factor authentication in the "My Profile" dialog, with recovery codes (Paperless-ngx docs, as of Nov 8, 2026).


Conclusion

You now have a document management system on your own server. Scan, find, stay in control.

The same VPS can also run Vaultwarden as a password manager, Immich for photos or your own VPN. Current prices are in the VPS comparison.


Frequently Asked Questions

How long does OCR take?
It depends on CPU and page count. Processing runs in the background, in parallel on multi-core systems.
Does Paperless recognize handwriting?
Paperless recognizes text via OCR (OCRmyPDF with Tesseract). The docs say nothing about handwriting; check with your own sample documents.
Can I import existing PDFs?
Yes. Put the PDFs in the consume folder. In the default auto mode, Paperless skips OCR for PDFs that already contain text.
Is there a mobile app?
The project wiki lists third-party apps for Android and iOS. The Paperless team doesn't support them.
How much RAM and CPU does Paperless-ngx need?
The docs give no minimums. Per the FAQ, Paperless also runs on a Raspberry Pi 3 B, but parts like OCR are then very slow. The Paperless calculator gives an estimate.
What happens to the original document after scanning?
Paperless doesn't change the original and creates an archive version for scanned documents. Whether you may destroy paper originals after scanning depends on retention rules, for businesses in Germany e.g. § 147 AO. If in doubt, ask your tax advisor.

Ready for a paperless office?

The Paperless calculator estimates how much RAM and storage your archive needs.

Open Paperless calculator

Next step: the cheapest plans for Paperless-ngx

The cheapest plans with at least 4 GB RAM, 2 vCPU and 40 GB storage, sorted by price. For Paperless-ngx these are the defaults of our calculator.

Prices incl. VAT · Prices as of Nov 18, 2026 · How we rank (methodology)

Compare all 60 matching plans →

Matching VPS Calculator

Paperless-ngx Hosting 2026: VPS für dein papierloses Büro

Rechnungen scannen, Verträge archivieren, alles durchsuchbar – auf deinem eigenen Server.

Go to Calculator

Related Articles