How to Self-Host Paperless-ngx: Go Paperless in 2026
Tutorials April 1, 2026 • 8 min read

How to Self-Host Paperless-ngx: Go Paperless in 2026

H

Hostly Team

Self-Hosting Enthusiast

Transform your paper chaos into a searchable digital archive. This complete guide covers deploying Paperless-ngx with Docker, OCR configuration, mobile scanning, and smart auto-tagging — all for free.

Paper is the enemy of organization. Receipts pile up in drawers. Important documents get lost in filing cabinets. Tax time becomes an archaeological expedition through boxes of forgotten paperwork. But in 2026, going paperless isn't just possible — it's practical, powerful, and completely free with self-hosted solutions.

Paperless-ngx is the leading open-source document management system for self-hosters. It scans your documents, extracts text using OCR, automatically tags and categorizes them, and makes everything instantly searchable. Think of it as Google for your paper documents — except you own all the data.

In this comprehensive guide, we'll deploy Paperless-ngx from scratch, configure intelligent auto-tagging, set up mobile scanning, and create a workflow that eliminates paper from your life forever.

Why Paperless-ngx?

Before we dive in, let's understand what makes Paperless-ngx special:

  • Powerful OCR — Extracts text from scanned documents, making them fully searchable
  • Smart Matching — Automatically assigns tags, document types, and correspondents based on content
  • Full-Text Search — Find any document instantly by searching its contents
  • Mobile Scanning — Scan documents directly from your phone
  • Consumption Folder — Drop PDFs and images into a folder, they're automatically processed
  • Email Import — Forward emails to Paperless-ngx for automatic archiving
  • Multi-User — Share with family or team members with permission controls
  • Archive Preservation — Original files are always preserved alongside OCR versions

Prerequisites

Before we begin, you'll need:

  • A server or PC — 2GB RAM minimum, 4GB+ recommended
  • Docker installed — We'll use Docker Compose for deployment
  • Storage space — Plan for 1-2GB per 1,000 documents (varies by file size)
  • Optional: Scanner — Any scanner or multi-function printer that produces PDFs

Step 1: Create the Directory Structure

First, set up a clean directory structure for Paperless-ngx:

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

Here's what each directory does:

  • data — Database and configuration
  • media — Processed documents and thumbnails
  • export — Exported document bundles
  • consume — Drop files here for automatic processing

Step 2: Deploy with Docker Compose

Create a docker-compose.yml file:

# docker-compose.yml for Paperless-ngx
services:
  broker:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped
    volumes:
      - ./redis-data:/data

  db:
    image: postgres:15
    container_name: paperless-db
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless-secure-password

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless-ngx
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "curl", "-fs", "-S", "--max-time", "2", "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: db
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: paperless-secure-password
      PAPERLESS_DBNAME: paperless
      PAPERLESS_SECRET_KEY: change-this-to-a-long-random-string
      PAPERLESS_URL: https://docs.yourdomain.com
      PAPERLESS_TIME_ZONE: Europe/Paris
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: your-admin-password

Start Paperless-ngx:

docker compose up -d

Wait about 30 seconds for initialization, then access the web interface at http://your-server-ip:8000.

Step 3: Initial Configuration

Log in with the admin credentials you set in the docker-compose file. Then configure these essential settings:

OCR Language

If you have documents in multiple languages, add more OCR languages:

# In docker-compose.yml, change:
PAPERLESS_OCR_LANGUAGE: eng+fra+deu

Supported languages include: eng (English), fra (French), deu (German), spa (Spanish), ita (Italian), por (Portuguese), nld (Dutch), and many more.

Document Types

Go to Admin → Document Types and create types for your document categories:

  • Invoice
  • Receipt
  • Contract
  • Bank Statement
  • Tax Document
  • Medical Record
  • Insurance
  • Manual/Documentation

Correspondents

Create correspondents for organizations you interact with frequently:

  • Your bank
  • Utility companies
  • Insurance providers
  • Government agencies
  • Healthcare providers

Tags

Create tags for cross-cutting categories:

  • Important
  • Action Required
  • Tax Deductible
  • Warranty
  • Personal / Business

Step 4: Configure Smart Auto-Tagging

Paperless-ngx's killer feature is automatic classification. It learns from your document patterns and applies tags automatically.

Auto-Matching Rules

Go to Admin → Matching to create rules. Examples:

Rule: Utility Bills

  • Match: Content contains "electricity" OR "gas" OR "water" OR "utility"
  • Assign: Tag "Utilities", Document Type "Invoice"

Rule: Bank Statements

  • Match: Content contains "account statement" OR "balance forward"
  • Assign: Document Type "Bank Statement", Correspondent "Your Bank"

Rule: Tax Documents

  • Match: Content contains "W-2" OR "1099" OR "tax return"
  • Assign: Tag "Tax", Tag "Important"

Machine Learning Classification

After you've manually classified 50-100 documents, Paperless-ngx can learn patterns and suggest classifications automatically. Enable this in Settings:

# Add to docker-compose.yml environment:
PAPERLESS_ENABLE_ASN: true
PAPERLESS_AUTO_CLASSIFY_CORRESPONDENTS: true
PAPERLESS_AUTO_CLASSIFY_TAGS: true
PAPERLESS_AUTO_CLASSIFY_DOCUMENT_TYPES: true

Step 5: Set Up the Consumption Folder

The consumption folder is where the magic happens. Drop any PDF, image, or office document into this folder, and Paperless-ngx automatically:

  1. Converts to PDF/A (archival format)
  2. Runs OCR to extract text
  3. Applies matching rules for auto-tagging
  4. Generates thumbnails
  5. Makes the document searchable

Connecting a Scanner

Most scanners can save directly to a network folder. Configure your scanner to save to the consume directory. For network scanners:

  1. Share the consume folder via SMB/Samba
  2. Configure your scanner to save to \\your-server\consume
  3. Scan documents — they appear in Paperless-ngx automatically

Consumption Folder Options

# Add to docker-compose.yml environment:
PAPERLESS_CONSUMER_POLLING: 60  # Check for new files every 60 seconds
PAPERLESS_CONSUMER_DELETE_DUPLICATES: true  # Remove duplicate files
PAPERLESS_CONSUMER_RECURSIVE: true  # Scan subfolders
PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS: true  # Use folder names as tags

With CONSUMER_SUBDIRS_AS_TAGS, you can organize dropped files into subfolders, and those folder names become tags automatically.

Step 6: Mobile Scanning Setup

For scanning on the go, you have several excellent options:

Option A: Paperless Mobile App (Android/iOS)

The community has built dedicated mobile apps:

  • Android: Paperless Mobile (F-Droid and Play Store)
  • iOS: Paperless for iOS (App Store)

Configure with your server URL and credentials. You can scan documents directly from the app.

Option B: Any Scanner App + Share

Use any document scanner app (Adobe Scan, Microsoft Lens, Genius Scan) and share the resulting PDF to Paperless-ngx via the mobile app or web upload.

Option C: Email Import

Configure Paperless-ngx to monitor an email inbox and import attachments:

# Add to docker-compose.yml environment:
PAPERLESS_EMAIL_HOST: imap.gmail.com
PAPERLESS_EMAIL_PORT: 993
PAPERLESS_EMAIL_HOST_USER: [email protected]
PAPERLESS_EMAIL_HOST_PASSWORD: your-app-password
PAPERLESS_EMAIL_FROM: [email protected]

Now forward or send scanned documents to that email address, and they're automatically imported.

Step 7: Set Up Remote Access

To access Paperless-ngx from anywhere, set up a reverse proxy with HTTPS:

Using Caddy (Recommended)

# Caddyfile
docs.yourdomain.com {
    reverse_proxy localhost:8000
}

Using Nginx Proxy Manager

Add a new proxy host pointing to your Paperless-ngx container on port 8000, enable SSL with Let's Encrypt.

Step 8: Backup Strategy

Your documents are valuable. Set up automatic backups:

Built-in Export

Paperless-ngx can export all documents with metadata:

# Run inside the container
docker exec paperless-ngx document_exporter /usr/src/paperless/export

Schedule this with cron for regular backups.

Directory Backup

Back up these directories:

  • ./data — Database and search index
  • ./media — All documents and thumbnails
# Example backup script
#!/bin/bash
tar -czf paperless-backup-$(date +%Y%m%d).tar.gz ./data ./media
# Upload to cloud storage or off-site location

Pro Tips for Document Management

ASN (Archive Serial Numbers)

Enable ASN to assign unique serial numbers to physical documents. Write the number on the physical document before scanning — now you can find the original if needed.

PAPERLESS_ENABLE_ASN: true

Date Detection

Paperless-ngx automatically extracts dates from document content. You can also set date formats for your region:

PAPERLESS_DATE_ORDER: DMY  # European date format (DD/MM/YYYY)

Filename Formatting

Customize how exported files are named:

PAPERLESS_FILENAME_FORMAT: "{created_year}/{correspondent}/{title}"

Trash Instead of Delete

Keep deleted documents in trash for recovery:

PAPERLESS_TRASH_DIR: /usr/src/paperless/media/trash

Integration with Other Tools

Nextcloud Integration

Mount your Nextcloud storage as the consume folder. Scan documents to Nextcloud from your phone, and they automatically appear in Paperless-ngx.

Home Assistant

Use Paperless-ngx's API to create automations — for example, notify when a new bill arrives.

n8n / Node-RED

Automate workflows: when a document with tag "Action Required" is added, send a notification or create a task.

Complete docker-compose.yml

Here's a full production-ready configuration:

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

  db:
    image: postgres:15
    container_name: paperless-db
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: change-this-password

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless-ngx
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      # Core settings
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: change-this-password
      PAPERLESS_DBNAME: paperless
      PAPERLESS_SECRET_KEY: generate-a-long-random-string-here
      
      # Server settings
      PAPERLESS_URL: https://docs.yourdomain.com
      PAPERLESS_TIME_ZONE: Europe/Paris
      
      # Admin user
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: change-this-admin-password
      
      # OCR settings
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_OCR_MODE: skip_noarchive
      
      # Consumer settings
      PAPERLESS_CONSUMER_POLLING: 30
      PAPERLESS_CONSUMER_DELETE_DUPLICATES: true
      PAPERLESS_CONSUMER_RECURSIVE: true
      PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS: true
      
      # Classification
      PAPERLESS_ENABLE_ASN: true
      
      # Date handling
      PAPERLESS_DATE_ORDER: DMY

Troubleshooting

OCR Not Working

  • Check that the OCR language is installed: docker exec paperless-ngx tesseract --list-langs
  • For additional languages, add them to PAPERLESS_OCR_LANGUAGE

Documents Not Being Consumed

  • Check folder permissions: the container needs read/write access
  • Look at logs: docker logs paperless-ngx
  • Verify the consume folder is mounted correctly

Slow Performance

  • OCR is CPU-intensive — give the container more resources
  • Consider limiting concurrent OCR tasks: PAPERLESS_TASK_WORKERS: 2
  • Use SSD storage for the database

Search Not Finding Documents

  • Rebuild the search index: docker exec paperless-ngx document_index --rebuild
  • Check that OCR completed successfully for the document

Frequently Asked Questions

How much storage do I need?

Plan for 1-5MB per document on average. A typical household might accumulate 500-1000 documents per year, requiring 2-5GB annually. Most home setups can start with 50-100GB.

Can I import existing PDFs?

Yes! Just drop them in the consume folder. Paperless-ngx will OCR them (if needed) and add them to your archive.

Is my data secure?

With self-hosting, your documents never leave your server. Use HTTPS for remote access, and keep your server updated.

Can multiple people use it?

Yes, Paperless-ngx supports multiple users with permission controls. Each user can have their own documents or share with others.

What file formats are supported?

PDF, images (JPEG, PNG, TIFF), and with optional packages: Office documents (DOCX, XLSX, PPTX), plain text, and more.

Conclusion

Paper clutter is a solved problem. With Paperless-ngx, you can scan, organize, and search decades of documents in seconds. The initial setup takes an afternoon; the time saved lasts forever.

Start by scanning your most recent documents — bills, receipts, important paperwork. As you build the habit, work backward through your filing cabinets. Within a few months, you'll wonder how you ever managed without it.

Your documents, searchable, organized, and completely under your control. That's the power of self-hosting.

Explore more document management tools in our Document Management category, or check out Paperless-ngx on Hostly for deployment templates.