Paperless-ngx: Self-Hosted Document Management System (2026)

In the era of paperless offices, there's a powerful open-source tool that empowers you to bring the same efficiency to your home life. Paperless-ngx is a complete document management system designed to be self-hosted, enabling you to digitize, organize, and retrieve your important paperwork with ease. This guide will walk you through setting it up on your own low-power home server using Docker, turning your homelab into a personal digital filing cabinet.

What It Is and Why Self-Host It

Paperless-ngx is a fork and evolution of the original Paperless project, built as a modern web application for archiving, indexing, and retrieving your digital documents. It's not just a digital shoebox; it's an intelligent system. When you upload or scan a document, it performs Optical Character Recognition (OCR) to extract text, making the contents fully searchable. You can then tag documents, assign them to correspondents (like "Utility Company"), categorize them into document types (like "Invoice"), and store them in logical folders. The core value is the ability to instantly find any document—a warranty, a tax form, or a medical bill—by searching for words you remember were on it.

Self-hosting Paperless-ngx offers significant advantages over cloud-based alternatives like Google Drive or proprietary document scanners:

• Privacy & Security: Your sensitive documents—tax returns, contracts, bank statements—never leave your personal network. You have complete control over the data.
• Cost: It's free. While some cloud services have subscription fees, Paperless-ngx runs on hardware you already own.
• Customization & Integration: You have full control over the OCR engine, scanner integration, and automation rules. You can connect it to your physical scanner or use mobile apps for on-the-go scanning.
• Learning & Control: Running it in your homelab deepens your understanding of containerized applications, databases (PostgreSQL), search engines (Apache Tika), and automation, skills that are valuable in themselves.
• Long-Term Archival: You define the storage strategy and backup routines, ensuring your documents are preserved according to your standards, independent of any third-party service changes.

Prerequisites

Before diving into the installation, ensure your environment meets these basic requirements.

1. A Linux Server: This guide assumes a Debian/Ubuntu or Raspberry Pi OS (Debian-based) system. The commands will work on most Linux distributions.
2. Docker and Docker Compose: Paperless-ngx is deployed as a set of containers. You must have Docker Engine and the Docker Compose plugin installed.
3. Basic Command Line Familiarity: You'll need to execute a few commands in a terminal (SSH or directly).
4. A Dedicated Storage Location: Decide where you want Paperless' data (documents, database, configuration) to reside permanently on your server. A path like /opt/paperless or /home/youruser/paperless-data is typical.

To install Docker and Docker Compose on a fresh Debian/Ubuntu system, you can run the following:

# Update the package index
sudo apt update

# Install Docker and necessary tools
sudo apt install docker.io docker-compose-plugin

# Ensure the Docker daemon starts automatically
sudo systemctl enable docker --now

# Add your user to the docker group to run commands without sudo (log out/in after)
sudo usermod -aG docker $USER

For a Raspberry Pi running Raspberry Pi OS, the process is similar, but ensure you're using the 64-bit version (aarch64) for best compatibility.

Docker Compose Installation

The recommended and simplest way to run Paperless-ngx is via a docker-compose.yml file. This defines all necessary services (the web app, database, OCR engine, and message broker) and their relationships.

Create a new directory for your Paperless instance, navigate into it, and create the docker-compose.yml file.

mkdir ~/paperless-ngx
cd ~/paperless-ngx

Now, create the docker-compose.yml file with the following content. This is a standard, production-ready configuration that includes all core components.

version: "3.4"
services:
  broker:
    image: rabbitmq:latest
    restart: unless-stopped
    volumes:
      - broker-data:/var/lib/rabbitmq

  db:
    image: postgres:15
    restart: unless-stopped
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=paperless
      - POSTGRES_USER=paperless
      - POSTGRES_PASSWORD=paperless

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    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
      - ./config:/usr/src/paperless/config
    environment:
      - PAPERLESS_REDIS=redis://broker:6379
      - PAPERLESS_DBHOST=db
      - PAPERLESS_DBNAME=paperless
      - PAPERLESS_DBPASS=paperless
      - PAPERLESS_DBUSER=paperless
      - PAPERLESS_SECRET_KEY=change-this-to-a-long-random-string
      - PAPERLESS_URL=http://localhost:8000
      - PAPERLESS_TIME_ZONE=America/New_York
      - PAPERLESS_OCR_LANGUAGE=eng
      - PAPERLESS_CONSUMPTION_DIR=/usr/src/paperless/consume

volumes:
  broker-data:
  db-data:
  data:
  media:
  export:

Important: You must change the PAPERLESS_SECRET_KEY value to a long, random string. This key secures your session data. You can generate one with a simple Python command: python3 -c "import secrets; print(secrets.token_urlsafe(64))".

With the file saved, you can start Paperless-ngx with a single command:

docker compose up -d

The -d flag runs the containers in detached mode (in the background). Docker will pull the required images and start all services. The initial startup might take a minute, especially on slower hardware. Once complete, Paperless-ngx will be accessible at http://YOUR_SERVER_IP:8000.

Initial Configuration

Upon first accessing the web interface (http://YOUR_SERVER_IP:8000), you'll be greeted by a setup wizard. The first step is to create a superuser account. This account has full administrative privileges.

After creating the superuser, log in. You should now see the main dashboard. Before you start consuming documents, there are a few critical settings to configure under Settings > Administration.

1. Configure the Consumption Directory

This is the directory where Paperless-ngx automatically imports documents from. In our docker-compose.yml, we defined it as /usr/src/paperless/consume inside the container. We need to mount a host directory to this path.

Stop the services (docker compose down) and add a new volume mount to the webserver service in your docker-compose.yml:

webserver:
  # ... other configuration remains the same ...
  volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - export:/usr/src/paperless/export
      - ./config:/usr/src/paperless/config
      - ./consume:/usr/src/paperless/consume  # Add this line

Create the consume directory in your Paperless folder (mkdir consume) and restart the stack (docker compose up -d). Now, any file (PDF, JPEG, PNG, TIFF) placed in the ./consume directory on your host will be automatically imported, OCR-processed, and added to Paperless.

2. Set Up Email for Consumption (Optional but Powerful)

Paperless can also import documents via email. This is incredibly useful for digitizing bills or statements you receive electronically. Under Settings > Mail, configure an email account (e.g., a dedicated Gmail address) using IMAP. Paperless will periodically check this inbox, and any email with an attachment will have that attachment imported as a document. The email subject becomes the document title, and the body can be used for auto-tagging.

3. Basic OCR Settings

Under Settings > General, verify the OCR language is set correctly (eng for English). You can also enable "Skip documents that already have text" to speed up processing of digital PDFs that are already searchable.

Key Features & How to Use Them

Paperless-ngx's power lies in its features for organization and automation. Here’s how to leverage them in your daily workflow.

Tagging, Correspondents, and Document Types

These are the primary organizational pillars.

• Tags: Labels like tax-2025, to-shred, medical, warranty-active. Use them for flexible, cross-cutting categorization.
• Correspondents: The sender or issuer of the document, e.g., Electric Company, IRS, Doctor's Office.
• Document Types: The functional category of the document, e.g., Invoice, Bank Statement, Contract, Receipt.

Create these entities before mass importing documents. When you upload a document, you can manually assign these. The real magic, however, comes from Auto-Matching Rules.

Auto-Matching Rules

Under Settings > Automation, you can create rules that automatically assign tags, correspondents, and types based on document content.

For example, create a rule that:

• Matches: If document text contains "ACME Utility Company".
• Actions: Assign correspondent ACME Utility Company, assign document type Invoice, add tag urgent-payment.

This means any scanned bill from ACME Utility is fully categorized upon import without any manual intervention.

The Consumption Workflow – From Paper to Searchable Digital Document

This is the core day-to-day use case.

1. Scan: Use your physical scanner (like an Epson ES-400W or a Brother ADS-2700W) to scan a document to a networked folder. Configure the scanner to save PDFs directly to the ./consume directory on your Paperless server via SMB/CIFS (Windows Share).
2. Email: Forward an electronic bill (PDF) from your personal email to your dedicated Paperless ingestion email address.
3. Mobile App: Use the excellent community-built Paperless Mobile app (available for Android and iOS). Configure it to connect to your Paperless instance. You can take a photo of a receipt with your phone, and the app will upload it directly to Paperless via the API.
4. Manual Upload: Drag-and-drop files into the web interface's upload area.

Once in the consumption directory, Paperless processes the document: it converts it to a standard format (PDF/A for archiving), runs OCR (using Apache Tika), applies auto-matching rules, and stores it. The original and archived versions are stored in the media volume, and the extracted text is indexed for search.

Full-Text Search and Document Preview

After processing, go to the Documents view. Use the search bar to find documents by any word within their content. Searching for "warranty period 24 months" will find that specific product manual. Click any document to view the archived PDF with the OCR text layer overlay.

Performance on Low-Power Hardware

Paperless-ngx is exceptionally well-suited for low-power homelab servers. Its workload is asynchronous and bursty—it idles most of the time and only consumes CPU/RAM during document import and OCR processing.

Here’s a breakdown of typical resource usage on popular low-power platforms:

Key Takeaways for Low-Power Users:

• RAM is more critical than CPU: Ensure you have at least 4GB of total system RAM, with 2GB dedicated to Paperless. The 8GB Raspberry Pi 5 or an N100 system with 16GB is overkill but provides headroom for other services.
• OCR is the bottleneck: The OCR process is single-threaded per document but can queue multiple documents. Powerful cores (like the N100's) significantly improve the consumption experience.
• Database and Web Server are lightweight: The PostgreSQL and Redis services use minimal resources. The bulk of the memory footprint is from the Paperless-ngx Python application itself and the OCR engine during processing.

Tips & Best Practices

1. Start with a Clean Structure: Before importing your backlog of documents, spend time setting up your Correspondents, Types, and a logical Tag hierarchy. This makes auto-matching rules far more effective.
2. Use the "Consume" Directory as Your Scanner Target: Configure your physical scanner's "Scan to Network" function to save files directly to the consume directory via a mounted SMB share. This creates a true "scan-to-cloud" pipeline.
3. Implement a Pre-Shredding Tag: Create a tag like to-shred. Once you've confirmed a document is correctly archived and categorized in Paperless, you can add this tag. This gives you a clear list of papers that are ready for physical destruction.
4. Regularly Export Your Archive: Under Settings > Backup, use the "Download archive" function to get a ZIP file containing all your documents and the database. Schedule this (e.g., via a cron job calling the Paperless API) and store it in your existing backup routine (e.g., to an external drive or cloud storage).
5. Secure Your Instance: Since Paperless holds sensitive data:
   • Change the default paperless database password in the docker-compose.yml to a strong one.
   • Consider placing Paperless behind a reverse proxy (like Nginx Proxy Manager) and enabling HTTPS.
   • Use the built-in user management to create a non-admin user for daily use.
6. Optimize OCR for Your Language: If you have documents in multiple languages, set PAPERLESS_OCR_LANGUAGE to eng+fra+deu (English, French, German) in your docker-compose.yml environment variables to improve accuracy.

Troubleshooting

Problem: Documents are not automatically importing from the consume directory. Solution: Check that the volume mount is correct in your docker-compose.yml. Inside the Paperless container, run a test by executing docker compose exec webserver ls -la /usr/src/paperless/consume. Ensure the directory exists and has the correct permissions (read/write for the container). The consumer service runs periodically; a new document might take up to a minute to be picked up.

Problem: OCR is failing or producing gibberish text. Solution: First, verify the document is not corrupted. Check the PAPERLESS_OCR_LANGUAGE setting in your environment variables. For scanned images, ensure they are reasonably clear and upright. Paperless uses Apache Tika, which is robust, but poor scan quality (low resolution, skewed pages, heavy shadows) will lead to bad OCR.

Problem: The web interface is slow or unresponsive on a Raspberry Pi. Solution: This is often a memory issue. Check your total system memory usage with free -h. If you're running other services, consider limiting them or moving Paperless to a system with more RAM. You can also try reducing the Paperless worker count by adding PAPERLESS_WORKERS=1 to the webserver environment in your compose file.

Problem: "Login failed" after initial setup. Solution: You are likely using the wrong credentials. The setup wizard creates a superuser. Ensure you are logging in with that username and password. If lost, you can create a new superuser via command line: docker compose exec webserver python manage.py createsuperuser.

Problem: Email consumption is not working. Solution: Double-check your IMAP settings (server, port, SSL). Use an "App Password" if using Gmail. Check the Paperless logs for mail errors: docker compose logs webserver. The mail consumer runs on a schedule; it may not check instantly.

Conclusion

Paperless-ngx transforms the daunting task of document management into an automated, searchable, and secure digital archive. By self-hosting it on a low-power server like an Intel N100 mini PC or a Raspberry Pi 5, you gain complete control over your personal data without sacrificing performance or incurring ongoing costs. The initial setup via Docker Compose is straightforward, and the daily workflow—integrating a physical scanner, email, and a mobile app—becomes a seamless part of your life. Start by digitizing a small batch of recent documents, refine your auto-tagging rules, and gradually build your archive. You'll quickly find that the ability to locate any piece of paper in seconds is not just a convenience; it's a game-changer for home organization.