Paperless-ngx installieren: Die komplette Anleitung für Docker und Bare Metal

Paperless-ngx ist das beliebteste Open-Source-Dokumentenmanagementsystem (DMS) für Privatpersonen, Selbstständige und kleine Unternehmen. Es verwandelt Papierberge in durchsuchbare, digitale Archive – mit automatischer OCR-Texterkennung, intelligenter Klassifizierung und einer schnellen Volltextsuche. Doch bevor Sie Paperless-ngx nutzen können, steht die Installation an. Und genau hier scheitern viele Einsteiger.

In diesem umfassenden Guide zeigen wir Ihnen bei fokus it solutions zwei Wege zur Installation: die empfohlene Docker-Variante und die manuelle Bare-Metal-Installation. Außerdem erklären wir die wichtigsten Konfigurationsschritte, die Scanner-Integration, OCR-Einrichtung und den Import bestehender Dokumente.

Voraussetzungen: Was Sie für Paperless-ngx brauchen

Hardware-Anforderungen

Paperless-ngx ist nicht besonders ressourcenhungrig – aber die OCR-Verarbeitung (Texterkennung) benötigt durchaus Rechenleistung. Hier unsere Empfehlungen:

Wichtig: SSD-Speicher ist dringend empfohlen. Die Volltextsuche und die Datenbank profitieren enorm von schnellen Lese- und Schreibzugriffen. Eine klassische HDD macht Paperless-ngx spürbar langsamer.

Software-Voraussetzungen

• Betriebssystem: Linux (Debian 12, Ubuntu 22.04/24.04 empfohlen). macOS und Windows (via WSL2) sind möglich, aber nicht optimal.
• Docker und Docker Compose: Für die Docker-Installation (empfohlen)
• Python 3.10+: Für die Bare-Metal-Installation
• PostgreSQL 13+ oder SQLite: Als Datenbank (PostgreSQL empfohlen für Produktion)
• Redis: Für die Task-Queue und Hintergrundverarbeitung

Methode 1: Installation mit Docker (empfohlen)

Die Docker-Installation ist der einfachste und zuverlässigste Weg, Paperless-ngx zu betreiben. Alle Abhängigkeiten (Python, PostgreSQL, Redis, Tesseract OCR) sind im Container enthalten. Updates sind ein einziger Befehl, und es gibt keine Konflikte mit anderer Software auf Ihrem Server.

Schritt 1: Docker und Docker Compose installieren

Falls Docker noch nicht installiert ist, installieren Sie es auf Debian/Ubuntu mit folgenden Befehlen:

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Prüfen Sie die Installation mit docker --version und docker compose version.

Schritt 2: Paperless-ngx Docker-Compose-Datei herunterladen

Erstellen Sie ein Verzeichnis für Paperless-ngx und laden Sie die offizielle Docker-Compose-Datei herunter:

mkdir -p /opt/paperless-ngx
cd /opt/paperless-ngx
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

Schritt 3: Umgebungsvariablen konfigurieren

Erstellen Sie eine .env-Datei im selben Verzeichnis mit den wichtigsten Einstellungen:

# Grundeinstellungen
PAPERLESS_SECRET_KEY=ein-langer-zufaelliger-string-hier
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu
PAPERLESS_URL=https://paperless.ihredomain.de

# Datenbank
POSTGRES_DB=paperless
POSTGRES_USER=paperless
POSTGRES_PASSWORD=ein-sicheres-passwort

# OCR-Einstellungen
PAPERLESS_OCR_MODE=skip_noarchive
PAPERLESS_OCR_CLEAN=clean-final
PAPERLESS_OCR_DESKEW=true
PAPERLESS_OCR_ROTATE_PAGES=true

# Sprache der Weboberfläche
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=ein-sicheres-admin-passwort

Wichtig: Verwenden Sie für PAPERLESS_SECRET_KEY einen langen, zufälligen String. Sie können ihn mit openssl rand -hex 32 generieren. Ändern Sie auch die Datenbankpasswörter!

Schritt 4: Container starten

cd /opt/paperless-ngx
docker compose up -d

Docker lädt nun alle Images herunter und startet die Container. Das dauert beim ersten Mal einige Minuten. Prüfen Sie den Status mit:

docker compose ps
docker compose logs -f

Paperless-ngx ist anschließend unter http://IHRE-IP:8000 erreichbar. Melden Sie sich mit den Admin-Zugangsdaten aus der .env-Datei an.

Schritt 5: Reverse Proxy einrichten (optional, empfohlen)

Für den Produktivbetrieb empfehlen wir einen Reverse Proxy mit SSL-Zertifikat. Mit Nginx und Let's Encrypt sieht die Konfiguration so aus:

server {
    listen 443 ssl http2;
    server_name paperless.ihredomain.de;

    ssl_certificate /etc/letsencrypt/live/paperless.ihredomain.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/paperless.ihredomain.de/privkey.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Methode 2: Bare-Metal-Installation

Die Bare-Metal-Installation eignet sich für erfahrene Linux-Administratoren, die keine Docker-Umgebung nutzen möchten oder können. Sie bietet maximale Kontrolle, erfordert aber mehr manuellen Aufwand bei Installation und Updates.

Systemabhängigkeiten installieren

sudo apt update
sudo apt install -y python3 python3-pip python3-dev python3-venv \
  postgresql postgresql-client redis-server \
  imagemagick gnupg libpq-dev libmagic-dev \
  tesseract-ocr tesseract-ocr-deu unpaper ghostscript \
  icc-profiles-free qpdf liblept5 libxml2 libxslt1.1 \
  zlib1g gettext jbig2dec

Datenbank einrichten

sudo -u postgres psql -c "CREATE USER paperless WITH PASSWORD 'sicheres-passwort';"
sudo -u postgres psql -c "CREATE DATABASE paperless OWNER paperless;"

Paperless-ngx installieren

sudo useradd -r -s /bin/bash -d /opt/paperless paperless
sudo mkdir -p /opt/paperless/{media,data,consume,export}
cd /opt/paperless

# Aktuelles Release herunterladen
sudo -u paperless wget https://github.com/paperless-ngx/paperless-ngx/releases/latest/download/paperless-ngx-latest.tar.xz
sudo -u paperless tar xf paperless-ngx-latest.tar.xz --strip-components=1

# Python Virtual Environment erstellen
sudo -u paperless python3 -m venv venv
sudo -u paperless ./venv/bin/pip install -r requirements.txt

# Konfiguration
sudo -u paperless cp paperless.conf.example paperless.conf
# Bearbeiten Sie paperless.conf mit Ihren Einstellungen

# Datenbank-Migration
sudo -u paperless ./venv/bin/python3 src/manage.py migrate
sudo -u paperless ./venv/bin/python3 src/manage.py createsuperuser

Systemd-Services einrichten

Für den automatischen Start bei Systemboot erstellen Sie Systemd-Services für den Webserver, den Consumer und den Scheduler. Paperless-ngx liefert Vorlagen im Verzeichnis scripts/ mit, die Sie nach /etc/systemd/system/ kopieren und anpassen können.

Konfiguration im Detail

OCR-Sprachen konfigurieren

Paperless-ngx nutzt Tesseract OCR für die Texterkennung. Standardmäßig wird Englisch verwendet. Für deutsche Dokumente setzen Sie:

PAPERLESS_OCR_LANGUAGE=deu

Für mehrsprachige Dokumente (z.B. Deutsch und Englisch) verwenden Sie:

PAPERLESS_OCR_LANGUAGE=deu+eng

Tesseract unterstützt über 100 Sprachen. Für Docker-Installationen müssen zusätzliche Sprachpakete im Container installiert werden. Die gängigsten Sprachen sind bereits enthalten. Bei Bare Metal installieren Sie die gewünschten Pakete mit sudo apt install tesseract-ocr-fra tesseract-ocr-ita etc.

OCR-Modi

Paperless-ngx bietet verschiedene OCR-Modi, die Sie über die Variable PAPERLESS_OCR_MODE steuern:

• skip: Bereits OCR-verarbeitete PDFs werden übersprungen (Standard)
• skip_noarchive: Überspringe OCR, erstelle aber trotzdem ein PDF/A-Archiv
• redo: OCR wird immer neu durchgeführt, auch bei bereits verarbeiteten Dateien
• force: OCR wird erzwungen, vorhandener Text wird überschrieben

Für die meisten Anwendungsfälle empfehlen wir skip_noarchive. So werden bereits digitale PDFs (z.B. Rechnungen aus Online-Shops) nicht unnötig neu verarbeitet, aber trotzdem als langzeitarchivierungsfähiges PDF/A gespeichert.

Consume-Ordner und Datei-Import

Der Consume-Ordner ist das Herzstück des automatischen Imports. Jede Datei, die in diesem Ordner landet, wird automatisch von Paperless-ngx verarbeitet: OCR, Klassifizierung und Archivierung laufen vollautomatisch.

In der Docker-Installation ist der Consume-Ordner standardmäßig als Volume gemappt. In der docker-compose.yml finden Sie typischerweise:

volumes:
  - ./consume:/usr/src/paperless/consume

Alles, was Sie in /opt/paperless-ngx/consume/ auf dem Host ablegen, wird automatisch importiert.

Scanner-Integration: Dokumente automatisch importieren

Ein Dokumentenmanagementsystem ist nur so gut wie der Workflow, der Papierdokumente digitalisiert. Es gibt mehrere Wege, gescannte Dokumente in Paperless-ngx zu bekommen.

Scan-to-Folder (Netzwerkscanner)

Die eleganteste Lösung: Konfigurieren Sie Ihren Netzwerkscanner so, dass er gescannte Dokumente direkt in den Consume-Ordner von Paperless-ngx ablegt. Die meisten modernen Scanner von Brother, Fujitsu, Canon und HP unterstützen Scan-to-Folder (SMB/CIFS) oder Scan-to-FTP.

Für Scan-to-Folder richten Sie eine Samba-Freigabe auf Ihrem Paperless-Server ein, die auf den Consume-Ordner zeigt:

[paperless-consume]
path = /opt/paperless-ngx/consume
writable = yes
guest ok = no
valid users = scanner
create mask = 0644

Scan-to-FTP

Alternativ können Sie einen FTP-Server einrichten, dessen Zielverzeichnis der Consume-Ordner ist. Das ist besonders bei Scannern praktisch, die kein SMB unterstützen, aber FTP beherrschen. Ein einfacher vsftpd-Server genügt.

Smartphone als Scanner

Sie haben keinen Dokumentenscanner? Kein Problem. Smartphone-Apps wie Adobe Scan, Microsoft Lens, Genius Scan oder die Nextcloud-App mit Scan-Funktion erstellen hochwertige PDFs aus Fotos. Die gescannten PDFs können Sie per Nextcloud, E-Mail oder Webinterface in Paperless-ngx importieren.

E-Mail-Import

Paperless-ngx kann E-Mails automatisch abrufen und Anhänge importieren. Konfigurieren Sie ein IMAP-Postfach und Paperless-ngx prüft regelmäßig auf neue E-Mails mit PDF-Anhängen. Das ist ideal für digitale Rechnungen, die Sie per E-Mail erhalten:

PAPERLESS_EMAIL_HOST=imap.ihredomain.de
PAPERLESS_EMAIL_PORT=993
PAPERLESS_EMAIL_USERNAME=paperless@ihredomain.de
PAPERLESS_EMAIL_PASSWORD=sicheres-passwort
PAPERLESS_EMAIL_USE_SSL=true

Webinterface-Upload

Der einfachste Weg: Ziehen Sie Dateien per Drag & Drop in das Paperless-ngx-Webinterface. Unterstützt werden PDF, PNG, JPEG, TIFF und WebP. Mehrere Dateien können gleichzeitig hochgeladen werden.

Bestehende Dokumente importieren

Wenn Sie bereits eine Sammlung digitaler Dokumente haben (z.B. auf einer Festplatte oder in einem Cloud-Speicher), können Sie diese in einem Rutsch in Paperless-ngx importieren.

Massen-Import über den Consume-Ordner

Der einfachste Weg: Kopieren Sie alle Dokumente in den Consume-Ordner. Paperless-ngx verarbeitet sie nacheinander. Bei großen Mengen (tausende Dokumente) kann das Stunden oder sogar Tage dauern, da jedes Dokument OCR-verarbeitet wird.

Tipp: Verarbeiten Sie große Dokumentenmengen in Batches von 100–500 Dateien. So behalten Sie den Überblick und können die Klassifizierung zwischendurch prüfen und anpassen.

Import mit dem document_importer

Paperless-ngx bietet ein Management-Kommando für den strukturierten Import:

# Docker
docker compose exec webserver python3 manage.py document_importer /pfad/zum/export

# Bare Metal
./venv/bin/python3 src/manage.py document_importer /pfad/zum/export

Der document_importer importiert Dokumente zusammen mit ihren Metadaten aus einem früheren Paperless-ngx-Export. Das ist ideal für Migrationen zwischen Servern.

Wichtige Konfigurationsoptionen

PDF/A-Archivierung

Paperless-ngx kann Dokumente automatisch in das PDF/A-Format konvertieren – ein ISO-Standard für die Langzeitarchivierung. Das ist besonders relevant für die GoBD-konforme Archivierung steuerrelevanter Dokumente:

PAPERLESS_OCR_OUTPUT_TYPE=pdfa

Dateinamen-Vorlagen

Mit der Variable PAPERLESS_FILENAME_FORMAT steuern Sie, wie archivierte Dateien auf der Festplatte benannt werden:

PAPERLESS_FILENAME_FORMAT={created_year}/{correspondent}/{title}

Das ergibt eine Ordnerstruktur wie 2026/Stadtwerke/Rechnung_Januar.pdf. Unterstützte Platzhalter sind u.a. {created_year}, {correspondent}, {document_type}, {title}, {asn} und {tag_list}.

Task-Concurrency

Standardmäßig verarbeitet Paperless-ngx ein Dokument nach dem anderen. Auf leistungsfähiger Hardware können Sie die parallele Verarbeitung aktivieren:

PAPERLESS_TASK_WORKERS=2
PAPERLESS_THREADS_PER_WORKER=2

Auf einem 4-Kern-System mit 8 GB RAM sind 2 Worker mit je 2 Threads ein guter Kompromiss zwischen Geschwindigkeit und Systemauslastung.

Updates und Wartung

Docker-Updates

Updates mit Docker sind denkbar einfach:

cd /opt/paperless-ngx
docker compose pull
docker compose up -d

Erstellen Sie vor jedem Update ein Backup Ihrer Daten:

docker compose exec webserver python3 manage.py document_exporter /usr/src/paperless/export

Backup-Strategie

Ein regelmäßiges Backup ist unverzichtbar. Sichern Sie folgende Verzeichnisse:

• media/: Enthält alle Originaldokumente und archivierten Versionen
• data/: Enthält den Suchindex
• PostgreSQL-Datenbank: Enthält alle Metadaten, Tags, Korrespondenten etc.

Ein einfaches Backup-Skript für Docker:

#!/bin/bash
BACKUP_DIR=/backup/paperless/$(date +%Y-%m-%d)
mkdir -p $BACKUP_DIR
docker compose exec -T webserver python3 manage.py document_exporter - > $BACKUP_DIR/export.zip
docker compose exec -T db pg_dump -U paperless paperless > $BACKUP_DIR/database.sql

Oder einfach: Managed Paperless-ngx Hosting

Die Installation und Wartung von Paperless-ngx erfordert Linux-Kenntnisse, regelmäßige Updates und eine durchdachte Backup-Strategie. Wenn Sie sich lieber auf Ihre Dokumente als auf die Server-Administration konzentrieren möchten, ist unser Managed Paperless-ngx Hosting die richtige Wahl.

Wir bei fokus it solutions übernehmen Installation, Konfiguration, Updates, Backups und Monitoring. Sie erhalten eine fertig eingerichtete Paperless-ngx-Instanz auf deutschen Servern – inklusive SSL, eigener Domain und persönlichem Support.

Häufig gestellte Fragen (FAQ)

Ist Docker oder Bare Metal besser für Paperless-ngx?

Docker ist für die meisten Nutzer die bessere Wahl: einfachere Installation, saubere Updates und keine Konflikte mit anderer Software. Bare Metal eignet sich für erfahrene Administratoren, die volle Kontrolle über jeden Aspekt der Installation haben möchten. Oder Sie nutzen unser Managed Hosting und müssen sich um nichts davon kümmern.

Welche Hardware brauche ich für Paperless-ngx?

Für den Einstieg reichen 2 CPU-Kerne, 4 GB RAM und 50 GB SSD-Speicher. Die OCR-Verarbeitung ist CPU-intensiv – bei großen Dokumentenmengen empfehlen wir 4 Kerne und 8 GB RAM. Auch ein Raspberry Pi 4 mit 4 GB RAM funktioniert, ist bei der OCR aber deutlich langsamer.

Kann ich meinen vorhandenen Scanner nutzen?

Ja, fast jeder Scanner funktioniert mit Paperless-ngx. Entscheidend ist, dass der Scanner als PDF oder TIFF scannen kann. Ideal sind Geräte mit Scan-to-Folder- oder Scan-to-FTP-Funktion. Auch Smartphone-Apps wie Adobe Scan oder Microsoft Lens eignen sich hervorragend.

Welche OCR-Sprachen unterstützt Paperless-ngx?

Paperless-ngx nutzt Tesseract OCR mit über 100 Sprachen. Für deutsche Dokumente setzen Sie PAPERLESS_OCR_LANGUAGE=deu. Mehrere Sprachen können kombiniert werden, z.B. deu+eng für deutsch-englische Dokumente.