How to Set Up Paperless-ngx on Docker — Complete Guide (2026)

Going paperless isn’t just an environmental choice — it’s about taking control of your documents, making them searchable, and never losing an important piece of paper again. Paperless-ngx is the most powerful open-source document management system available in 2026, offering OCR, automated tagging, full-text search, and a modern web interface that makes organizing thousands of documents effortless.

💡 This article contains affiliate links. If you buy through them, we earn a small commission at no extra cost to you. Learn more.

In this comprehensive guide, you’ll learn how to self-host Paperless-ngx on Docker, configure automated workflows, set up scanners, implement best practices for tagging and organization, and create a bulletproof document archive that works exactly the way you want it to.

What is Paperless-ngx?

Paperless-ngx is a community-driven fork of the original Paperless project, offering significant improvements and active development. It’s designed to transform your physical documents into a searchable digital archive.

Core capabilities:

OCR (Optical Character Recognition) — Automatically extracts text from scanned documents using Tesseract
Full-text search — Find any document instantly, even if you only remember a few words
Smart tagging — Automatic classification using machine learning and custom rules
Email import — Forward documents directly to your archive
Mobile apps — iOS and Android apps for scanning and uploading on the go
Automated workflows — Process documents based on content, sender, or type
Multi-user support — Share documents with family or team members
API access — Integrate with other tools and automation systems

Unlike cloud-based alternatives like Evernote or Google Drive, Paperless-ngx gives you complete ownership of your data, runs on your own hardware, and doesn’t charge monthly fees based on document count.

Why Choose Paperless-ngx in 2026?

Active development: The project receives regular updates, security patches, and new features. The community is vibrant and helpful.

Superior OCR: Paperless-ngx supports multiple OCR engines and languages, with accuracy that rivals commercial solutions.

Privacy-first: Your documents never leave your server. Medical records, financial statements, legal documents — all stay under your control.

Cost-effective: After initial setup, there are no subscription fees. Archive millions of pages without worrying about storage limits or per-page pricing.

Powerful automation: Create rules that automatically tag, categorize, and route documents based on content analysis.

Prerequisites

Before starting, ensure you have:

A Linux server running Ubuntu 22.04/24.04, Debian 11/12, or similar (2+ CPU cores, 4GB+ RAM recommended)
Docker and Docker Compose installed (follow our Docker installation guide if needed)
100GB+ storage for document archive (requirements grow with your collection)
Basic command-line knowledge
(Optional) A document scanner — we recommend the Brother ADS-2700W or Fujitsu ScanSnap iX1600

Step 1: Create the Directory Structure

Set up organized directories for Paperless-ngx:

1
2
mkdir -p ~/paperless-ngx/{data,media,export,consume}
cd ~/paperless-ngx

Directory purposes:

data/ — SQLite database and application files
media/ — Processed documents and thumbnails
export/ — Backup exports
consume/ — Drop new documents here for automatic import

Step 2: Create the Docker Compose Configuration

Create docker-compose.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
version: "3.8"

services:
  broker:
    image: redis:7-alpine
    container_name: paperless-broker
    restart: unless-stopped
    volumes:
      - redis_data:/data

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless-ngx
    restart: unless-stopped
    depends_on:
      - broker
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 5
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: 
      PAPERLESS_TIME_ZONE: Europe/Berlin
      PAPERLESS_OCR_LANGUAGE: eng+deu
      PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY}
      PAPERLESS_ADMIN_USER: ${PAPERLESS_ADMIN_USER}
      PAPERLESS_ADMIN_PASSWORD: ${PAPERLESS_ADMIN_PASSWORD}
      # OCR settings
      PAPERLESS_OCR_MODE: skip_archive
      PAPERLESS_OCR_SKIP_ARCHIVE_FILE: never
      PAPERLESS_OCR_OUTPUT_TYPE: pdfa
      PAPERLESS_OCR_PAGES: 0
      PAPERLESS_OCR_IMAGE_DPI: 300
      # Email settings (optional)
      PAPERLESS_EMAIL_TASK_CRON: "*/10 * * * *"
      # Consumer settings
      PAPERLESS_CONSUMER_POLLING: 5
      PAPERLESS_CONSUMER_DELETE_DUPLICATES: true
      PAPERLESS_CONSUMER_RECURSIVE: true
      # Tika (optional - better text extraction)
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      # Security
      PAPERLESS_ALLOWED_HOSTS: paperless.yourdomain.com,localhost
      PAPERLESS_CORS_ALLOWED_HOSTS: http://localhost:8000,https://paperless.yourdomain.com
      PAPERLESS_COOKIE_PREFIX: paperless_
      PAPERLESS_ENABLE_HTTP_REMOTE_USER: false

  # Optional: Tika for better text extraction
  tika:
    image: ghcr.io/paperless-ngx/tika:latest
    container_name: paperless-tika
    restart: unless-stopped

  # Optional: Gotenberg for Office document conversion
  gotenberg:
    image: gotenberg/gotenberg:7
    container_name: paperless-gotenberg
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-routes=true"

volumes:
  redis_data:

Step 3: Configure Environment Variables

Create .env file for secrets:

1
2
# Generate a secure secret key
openssl rand -base64 32

Create .env:

1
2
3
PAPERLESS_SECRET_KEY=your_generated_secret_key_here
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=ChangeThisSecurePassword123!

Security note: Use a strong password. This account has access to all your documents.

Step 4: Launch Paperless-ngx

Start the containers:

1
docker compose up -d

Check logs to ensure everything started correctly:

1
docker compose logs -f webserver

Wait for the message: Starting Paperless-ngx web server...

Access the web interface at http://your-server-ip:8000 and log in with the credentials from your .env file.

Step 5: Initial Configuration

Language and OCR Settings

Navigate to Settings → General and configure:

Date format: Choose your preferred format (YYYY-MM-DD recommended for sorting)
OCR languages: Install additional language packs if needed
Filename format: Set how archived documents should be named

Document Types

Create document types for organization:

Finance — Bank statements, invoices, receipts
Medical — Insurance documents, prescriptions, lab results
Legal — Contracts, agreements, certifications
Personal — ID cards, passports, certificates
Home — Manuals, warranties, utility bills

Go to Settings → Document Types and create these categories.

Correspondents

Add frequent senders/recipients:

Your bank
Insurance companies
Utility providers
Government agencies
Employers

This enables powerful filtering and automatic classification.

Step 6: Set Up Automated Workflows

Paperless-ngx can automatically process documents based on content.

Example: Auto-tag Bank Statements

Go to Settings → Workflows:

Name: Bank Statement Auto-Tag
Trigger: Content contains “Account Statement” OR filename contains “statement”
Actions:
- Set document type: Finance
- Add tag: #banking
- Set correspondent: Your Bank Name
- Archive automatically

Example: Invoice Processing

Name: Invoice Processing
Trigger: Content contains “Invoice Number” OR “Total Due”
Actions:
- Set document type: Finance
- Add tag: #invoice
- Add tag: #action-required
- Extract due date (if available)

Example: Medical Records

Name: Medical Document Classification
Trigger: Correspondent is “Health Insurance” OR content contains “patient”
Actions:
- Set document type: Medical
- Add tag: #medical
- Add tag: #reference

Step 7: Configure Email Import

Enable email-to-Paperless functionality:

Edit your docker-compose.yml and add email settings:

1
2
3
4
5
6
7
      PAPERLESS_EMAIL_TASK_CRON: "*/10 * * * *"
      PAPERLESS_CONSUMER_IMAP_SERVER: imap.gmail.com
      PAPERLESS_CONSUMER_IMAP_PORT: 993
      PAPERLESS_CONSUMER_IMAP_SECURITY: SSL
      PAPERLESS_CONSUMER_IMAP_USER: your-email@gmail.com
      PAPERLESS_CONSUMER_IMAP_PASSWORD: your-app-password
      PAPERLESS_CONSUMER_IMAP_MAILBOX: Paperless

For Gmail:

Enable 2FA on your Google account
Generate an app-specific password
Create a label called “Paperless”
Forward or filter emails to this label

Paperless will check every 10 minutes and import attachments from that folder.

Step 8: Scanner Integration

Network Scanners (Recommended)

Modern scanners like the Brother ADS-2700W or Fujitsu ScanSnap can save directly to network folders.

Configure your scanner to save to ~/paperless-ngx/consume/ via SMB/NFS:

Set up an SMB share pointing to the consume directory
Configure scanner to save to that network location
Paperless automatically picks up new files within seconds

Mobile Scanning

Use the official Paperless-ngx mobile app:

iOS: Paperless Mobile
Android: Available on F-Droid or Google Play

Scan documents with your phone camera, and they upload directly to your server.

Manual Upload

Simply drop PDF or image files into the consume/ directory, and Paperless processes them automatically.

Step 9: Backup Strategy

Protect your document archive:

Automated Exports

Paperless can export your entire archive regularly:

1
docker exec -it paperless-ngx document_exporter /usr/src/paperless/export

This creates a complete backup including documents, database, and metadata.

Scheduled Backups

Add to your crontab:

1
0 2 * * 0 cd ~/paperless-ngx && docker exec paperless-ngx document_exporter /usr/src/paperless/export && rsync -av export/ /mnt/backup/paperless/

This runs weekly at 2 AM, exports everything, and syncs to your backup location.

Database Backups

For SQLite database:

1
docker exec paperless-ngx sqlite3 /usr/src/paperless/data/db.sqlite3 ".backup '/usr/src/paperless/data/backup.sqlite3'"

Step 10: Security Hardening

Enable HTTPS

Use a reverse proxy like Traefik or Caddy to add HTTPS.

Example Traefik labels:

1
2
3
4
5
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.paperless.rule=Host(`paperless.yourdomain.com`)"
      - "traefik.http.routers.paperless.entrypoints=websecure"
      - "traefik.http.routers.paperless.tls.certresolver=letsencrypt"

Enable Two-Factor Authentication

Paperless supports TOTP 2FA:

Go to Settings → Security
Enable two-factor authentication
Scan QR code with your authenticator app

Restrict Access

Use environment variables to restrict access:

1
2
      PAPERLESS_ALLOWED_HOSTS: paperless.yourdomain.com
      PAPERLESS_ENABLE_HTTP_REMOTE_USER: false

Consider placing Paperless behind a VPN like Tailscale for additional security.

Advanced Tips and Best Practices

1. Consistent Naming Conventions

Set a filename template in Settings → General:

{created_year}/{correspondent}/{created_year}-{created_month}-{created_day} {title}

This creates organized folders by year and correspondent.

2. Use Custom Fields

Create custom fields for tracking:

Due Date — For bills and action items
Policy Number — For insurance documents
Account Number — For financial statements
Expiry Date — For warranties and subscriptions

3. Bulk Import Historical Documents

Got boxes of old documents? Scan them in batches:

Use a document feeder scanner
Drop all scans into consume/
Let Paperless process overnight
Review and tag in batches using the web interface

4. Leverage Full-Text Search

Paperless indexes every word. Search examples:

invoice AND 2026 — All 2026 invoices
correspondent:bank AND tag:statement — All bank statements
content:warranty expires — Documents mentioning warranty expiration

5. Create Smart Saved Searches

Save frequent queries:

Unpaid Invoices: tag:invoice AND tag:action-required
Tax Documents 2026: tag:tax-2026 OR (created:[2026-01-01 TO 2026-12-31] AND (correspondent:employer OR tag:donation))
Expiring Documents: Filter by custom “expiry date” field

Troubleshooting Common Issues

OCR Not Working

Check Tesseract installation:

1
docker exec -it paperless-ngx tesseract --list-langs

Install additional languages:

1
      PAPERLESS_OCR_LANGUAGE: eng+deu+fra+spa

High Memory Usage

Limit OCR resource consumption:

1
2
      PAPERLESS_OCR_PAGES: 10  # Limit pages processed
      PAPERLESS_TASK_WORKERS: 1  # Reduce parallel processing

Slow Processing

Enable Tika and Gotenberg (already in our compose file) for faster text extraction:

1
      PAPERLESS_TIKA_ENABLED: 1

Duplicate Documents

Enable automatic duplicate detection:

1
      PAPERLESS_CONSUMER_DELETE_DUPLICATES: true

Maintenance and Updates

Update Paperless-ngx

1
2
3
cd ~/paperless-ngx
docker compose pull
docker compose up -d

Check the release notes before major updates.

Optimize Database

Periodically optimize the SQLite database:

1
docker exec -it paperless-ngx python3 manage.py document_sanity_checker

Conclusion

Paperless-ngx transforms document chaos into organized, searchable digital archives. With OCR, automated tagging, email import, and powerful search capabilities, you’ll never lose a document again.

The investment in setting up Paperless-ngx pays dividends immediately — no more digging through filing cabinets, no more “where did I put that receipt?”, and complete control over your sensitive documents without relying on cloud services.

Start with a single category (like receipts or bank statements), build your workflows gradually, and before long you’ll have years of documents perfectly organized and instantly accessible.

Next steps:

Set up automated backups with Proxmox Backup Server
Secure access with Traefik and Let’s Encrypt
Monitor with Uptime Kuma

Have questions about Paperless-ngx? Join our community discussions or explore our other self-hosting guides.

What is Paperless-ngx?#

Why Choose Paperless-ngx in 2026?#

Prerequisites#

Step 1: Create the Directory Structure#

Step 2: Create the Docker Compose Configuration#

Step 3: Configure Environment Variables#

Step 4: Launch Paperless-ngx#

Step 5: Initial Configuration#

Language and OCR Settings#

Document Types#

Tags#

Correspondents#

Step 6: Set Up Automated Workflows#

Example: Auto-tag Bank Statements#

Example: Invoice Processing#

Example: Medical Records#

Step 7: Configure Email Import#

Step 8: Scanner Integration#

Network Scanners (Recommended)#

Mobile Scanning#

Manual Upload#

Step 9: Backup Strategy#

Automated Exports#

Scheduled Backups#

Database Backups#

Step 10: Security Hardening#

Enable HTTPS#

Enable Two-Factor Authentication#

Restrict Access#

Advanced Tips and Best Practices#

1. Consistent Naming Conventions#

2. Use Custom Fields#

3. Bulk Import Historical Documents#

4. Leverage Full-Text Search#

5. Create Smart Saved Searches#

Troubleshooting Common Issues#

OCR Not Working#

High Memory Usage#

Slow Processing#

Duplicate Documents#

Maintenance and Updates#

Update Paperless-ngx#

Optimize Database#

Conclusion#