Migrate from Papermerge to Paperless-ngx

• No more security patches: any vulnerability discovered after archiving will remain open — FastAPI and its dependencies publish several advisories per month
• Python compatibility declining: new Python versions drop deprecated APIs; an OS update is enough to break the environment
• Orphaned plugins and integrations: third-party connectors (scanners, mail clients, webhooks) will no longer be updated to follow Papermerge's REST API evolution
• No official schema migrations: if a database bug is discovered, no fix will come from the archived repository
• No contractual support coverage possible: no vendor will cover an installation on an archived project
• Ecosystem closing in: official Docker images stop being published, and unofficial images introduce a supply chain risk

• Multi-language OCR via Tesseract: French, Arabic, Spanish, English and dozens of other languages configurable via environment variables
• Hierarchical tags: fine-grained document organization with inherited automatic assignment rules
• Correspondents: identification of recurring senders/recipients, automatic assignment by rule
• S3-compatible storage: archive originals to an S3 or compatible bucket (MinIO, Garage) without modifying the interface
• Documented REST API: integration with external workflows (n8n, curl scripts) via /api/documents/
• Consume folder: any file dropped in /consume is automatically ingested — natural connection for network scanners and mail clients

Papermerge v3 vs Paperless-ngx

Scroll the table

• VPS: 2 vCPU / 2 GB RAM minimum — 4 GB recommended if OCR runs in parallel on multiple documents during ingestion
• Docker and Docker Compose: Docker ≥ 24, Docker Compose ≥ 2.20 (integrated plugin, not the legacy Python binary)
• 40 GB SSD storage minimum for originals + index data; plan for more depending on archive volume
• Domain or subdomain with a valid TLS certificate — Paperless-ngx does not require HTTPS but strongly recommends it for sessions and API tokens
• Root or sudo access on the VPS to install Docker and configure the reverse proxy
• Backup of your existing Papermerge instance before any operation: document export + database dump

Migrate from Papermerge to Paperless-ngx

1. 01

   Export your documents from Papermerge

   In the Papermerge interface, go to Documents → Export. Select "All documents" and start the export. Papermerge generates a ZIP file containing the originals (PDFs, images) organized by folder. Download this file to your local machine or transfer it directly to the target VPS via scp:

   scp papermerge-export.zip user@your-vps:/tmp/

2. 02

   Unzip the export and prepare the consume folder

   On the VPS, unzip the archive into a temporary directory:

   mkdir -p /opt/paperless-import
   unzip /tmp/papermerge-export.zip -d /opt/paperless-import/

   You get a directory tree of files. Paperless-ngx will consume these files via its consume folder in a later step.

3. 03

   Install Paperless-ngx via the official Docker Compose file

   Fetch the official docker-compose.yml from the Paperless-ngx repository:

   mkdir -p /opt/paperless && cd /opt/paperless
   curl -fsSL https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml -o docker-compose.yml
   curl -fsSL https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/.env.example -o .env

   Edit the .env file: set PAPERLESS_URL, PAPERLESS_SECRET_KEY (a long random string), PAPERLESS_OCR_LANGUAGE (e.g. fra+eng for French + English), and PAPERLESS_TIME_ZONE (Europe/Paris or your timezone).

4. 04

   Start the instance and create the administrator account

   Launch the containers in the background:

   docker compose up -d

   Wait for the service to be ready (30 to 60 seconds), then create the superuser:

   docker compose exec webserver python3 manage.py createsuperuser

   Log in at http://localhost:8000 (or your domain) to verify the interface responds.

5. 05

   Import documents exported from Papermerge

   Copy the exported directory tree into the Paperless-ngx consume folder. By default, this folder is the consume volume declared in docker-compose.yml:

   cp -r /opt/paperless-import/* /opt/paperless/consume/

   Paperless-ngx will automatically detect the new files and ingest them via Celery. You can monitor progress in the Logs tab of the interface or via:

   docker compose logs -f celeryworker

6. 06

   Configure the reverse proxy and TLS

   Expose Paperless-ngx behind nginx. Minimal block example for a subdomain:

   server {
       listen 443 ssl;
       server_name docs.your-domain.com;
       ssl_certificate /etc/letsencrypt/live/docs.your-domain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/docs.your-domain.com/privkey.pem;
       location / {
           proxy_pass http://127.0.0.1:8000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

   Obtain or renew a Let's Encrypt certificate for this subdomain, then reload nginx.

7. 07

   Verify OCR coverage and test imported documents

   In the Paperless-ngx interface, open several imported documents and verify their content is indexed (working search bar). For documents where OCR failed (warning icon), relaunch OCR manually from the interface or via the REST API:

   curl -X POST http://localhost:8000/api/documents/<id>/redo_ocr/ \
     -H 'Authorization: Token <your-token>'

8. 08

   Validate and shut down the old Papermerge instance

   After the full import, verify that the document count in Paperless-ngx matches your Papermerge export. Test full-text search on known terms, check attachments and downloadable originals. Once validation is complete, stop the Papermerge instance and remove its containers: docker compose down from its deployment directory.

• OCR: PAPERLESS_OCR_LANGUAGE accepts a list of Tesseract language codes separated by + (fra+eng+ara). If your corpus is multilingual, declare all languages from the start so imported documents are reprocessed correctly
• S3 storage: set PAPERLESS_STORAGE_BACKEND=s3, PAPERLESS_S3_ACCESS_KEY, PAPERLESS_S3_SECRET_KEY and PAPERLESS_S3_BUCKET_NAME to offload originals to an S3-compatible bucket — useful for multi-gigabyte corpora on a storage-limited VPS
• Automatic assignment rules: in the interface, create rules that assign a tag, correspondent, or document type based on OCR content (e.g. any document containing "invoice" → tag Invoices, correspondent Supplier X)
• Scheduled tasks: the Celery worker already handles automatic consumption; verify that PAPERLESS_CONSUMER_POLLING is 0 (inotify) or a reasonable interval if inotify is not available in your Docker environment

• Network scanner: configure your scanner to send scans via SFTP or SMB into /consume. Paperless-ngx ingests them on arrival, with no manual action required
• Mail client: the mail consumer (PAPERLESS_EMAIL_HOST, PAPERLESS_EMAIL_PORT) monitors an IMAP mailbox and automatically imports PDF attachments from messages matching your filters (subject, sender)
• REST API: the POST /api/documents/post_document/ endpoint accepts a multipart file. From n8n, a workflow can send any received email attachment directly to Paperless within seconds. The API token is generated under Settings → API Tokens
• Mobile app: the Paperless Mobile app (Android/iOS, open source) connects to your self-hosted instance via URL and API token

• Imported documents with no OCR text: verify the Tesseract language code is correct (PAPERLESS_OCR_LANGUAGE=fra not fr). Valid codes are listed in the Tesseract documentation. Relaunch OCR on affected documents via the interface or API
• Consume folder not monitored: if you use a Docker volume mounted from an NFS partition or object storage, inotify does not work. Set PAPERLESS_CONSUMER_POLLING=60 for a scan every 60 seconds
• "Permission denied" error on /consume: the Paperless worker runs as UID 1000. If files copied to /consume belong to root, change permissions: chown -R 1000:1000 /opt/paperless/consume/ on the host
• Incomplete import — missing documents: Papermerge exports documents in the folder structure visible in its interface. Documents in deeply nested folders are all exported, but filenames containing special characters may cause issues. Check with find /opt/paperless-import -name '*.pdf' | wc -l and compare to your Papermerge instance total