Hobbyist's Hideaway LogoHobbyist's Hideaway
HomeLab
•14 min read

Paperless-ngx Setup on Proxmox (2026): Self-Hosted Document Archive

Share
Paperless-ngx Setup on Proxmox (2026): Self-Hosted Document Archive
On this page(13 sections)

Paperless-ngx is a free, self-hosted document manager: you scan or email in your paperwork, it OCRs every page, files it with tags and correspondents, and makes everything searchable in seconds. On Proxmox you can have it running in about five minutes with the community helper-script LXC, or in fifteen with the official Docker Compose stack. This guide covers both, then the parts that actually make you paperless: a scanner workflow, OCR languages, automatic matching, email import, backups and optional AI tagging with a local Ollama.

What Is Paperless-ngx?

Paperless-ngx turns a pile of letters, bills, payslips and warranty cards into a searchable archive. Every document goes through the same pipeline:

  1. Consume: a file lands in the consume folder, the web upload, the mobile app or an email inbox.
  2. OCR: Tesseract (via OCRmyPDF) reads the text, even from photos and crooked scans.
  3. Archive: it stores your original plus a searchable PDF/A copy.
  4. Classify: matching rules (or its built-in machine learning) assign a correspondent, document type, tags and a storage path.
  5. Find: full-text search across everything, with filters like "all invoices from the electricity company in 2025".

It's the community-maintained successor of Paperless and Paperless-ng, licensed under GPL-3.0 and completely free. The 3.0 release in mid-2026 added native AI features (optional, off by default), which we cover below.

Hardware Requirements

Paperless-ngx is light. Most of the time it idles; it only works hard while OCRing new documents. These are rough, typical figures for a household:

SetupCPURAMNotes
Basic (Paperless + Postgres + Valkey)2 cores2–3 GBPlenty for a family's paperwork
+ Tika and Gotenberg2–4 cores3–4 GBAdds Office files (.docx, .xlsx) and full email (.eml) support
+ local AI (Ollama)4+ cores or a GPU8–16 GB extraBest on a separate, more powerful machine

Storage needs are small: thousands of scanned PDFs typically fit in a few GB.

An Intel N100 or N150 mini PC is more than enough, even alongside Jellyfin, Immich and Home Assistant. See our low-power N100 homelab guide and the N100 vs N150 vs N305 comparison if you're still choosing hardware.

Install Options on Proxmox

You have three sensible choices:

Helper-script LXCDocker Compose in an LXCDocker Compose in a VM
Setup timeAbout 5 minutesAbout 15 minutesAbout 20 minutes
OverheadLowestLowHighest
Install methodNative (no Docker)Official imagesOfficial images
Updatesupdate in the LXC consoledocker compose pulldocker compose pull
Matches official docsPartlyYesYes
Best forFastest startMost homelabsMaximum isolation

Use the helper script for the quickest start, or Docker Compose for the setup the official docs assume. New to Proxmox? Our Proxmox on N100 setup guide covers creating LXCs and VMs.

Option 1: Proxmox VE helper script (fastest)

The community-run Proxmox VE Helper-Scripts project has a one-line Paperless-ngx installer. Run it in the Proxmox host shell (Datacenter → your node → Shell):

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/paperless-ngx.sh)"

Choose Default for a quick install, or Advanced to set the container ID, storage, network and resources. The defaults are an unprivileged Debian 13 LXC with 2 vCPUs, 3 GB RAM and a 12 GB disk, which is fine to start; you can grow the disk later.

When it finishes, open http://CONTAINER-IP:8000. The generated admin login is saved in a paperless-ngx.creds file in the container's root home folder (cat ~/paperless-ngx.creds in the LXC console).

A few things to know:

  • It's a community project, not an official Paperless-ngx or Proxmox one, so read the script before running it.
  • It installs Paperless-ngx natively (no Docker), so settings live in Paperless's paperless.conf file instead of a compose env file. The variable names are the same.
  • To update, open the LXC console and run update.

Option 2: Docker Compose in an LXC or VM

Create a Debian LXC (enable nesting and keyctl under Options → Features so Docker works in an unprivileged container) or a small Debian VM, then install Docker. Our self-hosting with Docker guide covers the basics.

The official compose files live in the repository's docker/compose/ folder (SQLite or Postgres, with or without Tika). Here's a stack adapted from the Postgres + Tika variant:

# /opt/paperless/docker-compose.yml
services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    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
      - gotenberg
      - tika
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:latest
    restart: unless-stopped

volumes:
  data:
  media:
  pgdata:
  redisdata:

Don't need Office files or full email import? Delete the gotenberg and tika services and the three TIKA lines. To change the database password, set the same value in POSTGRES_PASSWORD and PAPERLESS_DBPASS.

Next, the settings file:

# /opt/paperless/docker-compose.env
USERMAP_UID=1000
USERMAP_GID=1000

# The URL you'll use to reach Paperless (needed behind a reverse proxy)
PAPERLESS_URL=https://paperless.example.com

# Generate with: openssl rand -hex 32
PAPERLESS_SECRET_KEY=replace-with-a-long-random-string

PAPERLESS_TIME_ZONE=Asia/Kathmandu
PAPERLESS_OCR_LANGUAGE=eng

Start it and create your admin user:

cd /opt/paperless
docker compose up -d
docker compose run --rm webserver createsuperuser

Open http://SERVER-IP:8000 and log in. For a production setup, replace :latest with a specific version tag so upgrades only happen when you choose.

The Consume Folder and Scanner Workflow

Document scanner feeding paper letters with digital pages flowing to a home server
Scan to a network folder and Paperless-ngx OCRs, tags and files every page for you.

The consume folder is the heart of a paperless workflow: anything dropped into it gets imported, then removed from the folder. The trick is getting your scanner to drop files there automatically.

Scan to SMB (network folder)

Most ADF document scanners and office multifunction printers can scan to a network folder. Share the consume folder over SMB:

  • Docker setup: share /opt/paperless/consume with Samba on the same LXC/VM, or point the bind mount at a folder on your NAS.
  • NAS route: create a scans share on TrueNAS or your NAS, mount it on the Paperless host, and use it as the consume folder. Our TrueNAS SCALE guide covers creating SMB shares.

Then configure your scanner's scan to folder profile with the share path and a dedicated user. Scan duplex, at 300 DPI, to PDF.

When the consume folder is on a network share, filesystem change notifications often don't work. Tell Paperless to poll instead:

PAPERLESS_CONSUMER_POLLING_INTERVAL=30

Scan to FTP or email

Some scanners only support FTP or email. Run a small FTP server container that writes into the consume folder, or have the scanner email an inbox that Paperless watches (see below).

Phone as a scanner

On iPhone, the Files app can connect to your SMB share and has a built-in Scan Documents option: scan a receipt and save it straight into the consume folder. On any phone, the Paperless-ngx web UI and community apps can upload directly.

Smart consume-folder tricks

# Subfolders become tags: consume/tax/receipts/scan.pdf gets "tax" and "receipts"
PAPERLESS_CONSUMER_RECURSIVE=true
PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true

# Use barcode separator sheets to split one big batch scan into documents
PAPERLESS_CONSUMER_ENABLE_BARCODES=true

OCR Languages

By default Paperless OCRs in English. Tesseract uses three-letter language codes, and you can combine several with +:

# Languages to use for OCR
PAPERLESS_OCR_LANGUAGE=eng+nep

# Docker only: extra language packs to install at container start
PAPERLESS_OCR_LANGUAGES=nep hin

The first variable tells Paperless which languages to use; the second installs the packs. Only add languages you actually receive mail in, since each one slows OCR down. Native installs, including the helper-script LXC, need the matching tesseract-ocr-* packages installed with apt.

Organise: Tags, Correspondents, Document Types

Paperless gives you a few building blocks. Getting them right early saves a lot of re-sorting later.

Building blockWhat it meansExamples
CorrespondentWho sent it (or who you sent it to)Your bank, the electricity company, your employer
Document typeWhat kind of document it isInvoice, Receipt, Payslip, Contract, Warranty
TagsAnything else; a document can have manytax-2026, car, house, important
Storage pathWhere the file sits on diskPer correspondent and year
Custom fieldsExtra structured dataAmount, due date, policy number

Two tips that make Paperless click:

  • Create an "Inbox" tag and mark it as an inbox tag in its settings. Every new document gets it automatically. Review, correct and remove the tag, and your inbox becomes a to-do list.
  • Keep types and tags few and broad. "Invoice" plus a correspondent beats a tag for every company.

Storage paths use templates. For example, this files documents as Correspondent/Year/Title.pdf:

{{ correspondent }}/{{ created_year }}/{{ title }}

Matching Rules and Workflows

Automatic matching

Every correspondent, document type, tag and storage path has a matching algorithm:

AlgorithmHow it worksUse it for
AutoLearns from documents you've already classifiedMost things, once you have some examples
Any / AllMatches if any (or all) of the words appearSimple keyword rules
ExactMatches an exact phraseAccount or customer numbers
Regular expressionMatches a regexInvoice number formats
FuzzyTolerates OCR typosMessy scans
NoneNever auto-assignedManual-only tags

Start with Auto everywhere. After you've correctly classified a few documents per category, Paperless gets surprisingly good. Use Exact for anything with a unique account or customer number; it's the most reliable rule there is.

Workflows

Workflows (under Settings or the sidebar, depending on version) are if-this-then-that rules. A workflow has triggers (consumption started, document added, document updated, or on a schedule) and actions (assign or remove tags, correspondents, owners, permissions and custom fields, send an email or call a webhook).

Some useful examples:

  • Everything from the scans/tax share gets the tax-2026 tag and is shared with your partner's account.
  • Documents of type Invoice trigger a webhook to Home Assistant or an email reminder.

Fetch Documents from Email

Many bills only arrive as PDF attachments. Paperless can collect them automatically:

  1. Go to Mail (Settings → Mail on some versions) and add a mail account with your IMAP server. For Gmail or Outlook, use an app password or the built-in OAuth option.
  2. Add a mail rule: which folder to watch, filters (sender, subject, body), whether to import attachments only or the whole email as PDF, and what to do afterwards (mark as read, move, flag or delete).
  3. Have the rule assign a correspondent, tags or document type directly, or leave it to matching.

Paperless checks mail every 10 minutes by default. Importing the full email as a PDF needs the Tika and Gotenberg containers from the compose file above. Tip: create a dedicated address and simply forward bills to it.

Optional: AI Tagging with a Local Ollama

Built-in AI in Paperless-ngx 3.x

Since version 3.0, Paperless-ngx has native AI features, disabled by default: suggestions for title, tags, correspondent and document type, chat with your documents, and a vector index for finding similar documents. It works with Ollama or any OpenAI-compatible API, so you can keep everything on your own hardware:

PAPERLESS_AI_ENABLED=true
PAPERLESS_AI_LLM_BACKEND=ollama
PAPERLESS_AI_LLM_ENDPOINT=http://192.168.1.60:11434
PAPERLESS_AI_LLM_MODEL=llama3.1

# Embeddings for document chat and similar-document search
PAPERLESS_AI_LLM_EMBEDDING_BACKEND=ollama
PAPERLESS_AI_LLM_EMBEDDING_MODEL=embeddinggemma

Pull the models on your Ollama machine first (ollama pull llama3.1 and ollama pull embeddinggemma). Newer 3.x releases can also apply AI suggestions automatically from a workflow action.

Hardware reality check: an 8B model on an N100's CPU works, but each document can take a long time. Our Ollama on N100 benchmarks show what to expect. Running Ollama on a PC with a GPU and pointing Paperless at it over the network is a much better experience. New to Ollama? Start with our local AI with Ollama and Open WebUI guide.

Third-party add-ons: paperless-gpt and paperless-ai

Before native AI existed, two community projects filled the gap:

  • paperless-gpt uses LLMs for titles, tags and correspondents, and can also use vision models for OCR, which helps with handwriting and poor scans.
  • paperless-ai offered automatic tagging and a RAG chat. It's reportedly no longer maintained, so prefer the native features for new installs.

Both connect through the Paperless API with a token and support Ollama.

Backups: document_exporter and 3-2-1

The document exporter

The document exporter writes every document, along with a manifest of all metadata (tags, correspondents, notes, users and settings), to plain files. It's the safest, version-independent way to back up:

cd /opt/paperless
docker compose exec -T webserver document_exporter ../export

That lands in the ./export bind mount. Add --zip for a single archive file. Schedule it nightly with cron:

# crontab -e
0 2 * * * cd /opt/paperless && docker compose exec -T webserver document_exporter ../export

On native installs, such as the helper-script LXC, run the same document_exporter command through Paperless's manage.py. To restore, run document_importer against the export on a fresh, empty instance.

A 3-2-1 plan

  • Copy 1: the live Paperless instance.
  • Copy 2: nightly Proxmox backups of the LXC/VM (ideally to Proxmox Backup Server) plus the exporter output copied to a NAS.
  • Copy 3: the exporter folder pushed off-site with an encrypted tool like restic or Borg (Backblaze B2, a friend's server).

We use the same approach for photos in our Immich backup guide.

Mobile Apps and Remote Access

The Paperless-ngx web UI is responsive and works well on a phone browser. Community apps add camera scanning and quick uploads:

  • iOS: Swift Paperless is a popular, actively developed native client.
  • Android: community clients have changed hands over the years, so check the Play Store or F-Droid for a recently updated Paperless-ngx app.

Paperless-ngx doesn't encrypt documents at rest, so don't expose it directly to the internet. Use a VPN like Tailscale (see Tailscale vs WireGuard), or a reverse proxy with HTTPS and two-factor authentication turned on in your Paperless profile. Our Traefik reverse proxy guide covers the proxy side; remember to set PAPERLESS_URL to your public address.

FAQ

Is Paperless-ngx free?

Yes. Paperless-ngx is open-source (GPL-3.0) with no paid tiers. Your only costs are the hardware, the electricity and, optionally, a document scanner.

What's the difference between Paperless, Paperless-ng and Paperless-ngx?

Paperless was the original, Paperless-ng a rewrite of it, and Paperless-ngx the community continuation, which is the only actively developed version. Ignore guides for the older two.

Should I run Paperless-ngx in an LXC or a VM on Proxmox?

An LXC uses less RAM and is perfect for Paperless, either via the helper script or Docker inside the LXC. Choose a VM if you want full isolation from the host or prefer to avoid Docker-in-LXC quirks.

Can Paperless-ngx run on a Raspberry Pi?

Yes. The Docker images support arm64, so a Raspberry Pi 4 or 5 with 4 GB of RAM or more works. OCR on large batches is slower than on an N100, but fine for a household's mail.

How do I update Paperless-ngx?

With Docker, run docker compose pull && docker compose up -d (after updating your pinned version tag). With the helper-script LXC, run update in the container console. Before major upgrades, such as 2.x to 3.x, read the release notes, take a Proxmox snapshot and run the exporter.

Conclusion

Once the scanner, consume folder and email rules are set up, Paperless-ngx files your paperwork for you. On Proxmox, start with the helper-script LXC for speed or Docker Compose for the official, well-documented path, add your OCR languages, lean on Auto matching and workflows, and run the document exporter nightly as part of a 3-2-1 backup. Add local AI with Ollama later, once the basics are solid.

Running out of things to self-host? Set up Immich for your photos next, or give your media server a makeover with the best Jellyfin plugins and themes.

Share this article
Share

Never Miss a Project

Join our community of makers. Get the latest guides on Homelab, Electronics, and Coding delivered to your inbox.