Paperless-ngx: scanner, setup and backups

The shoebox of letters under the desk is a database too, just one with terrible search. Paperless-ngx turns it into a searchable archive, if the scanner, the folder and the backup are planned in the right order.

The short answer

How do you set up Paperless-ngx at home? Run it with Docker Compose, point a folder on the host at the container's consumption directory, and let any scanner that can save files to a network folder drop PDFs there. Paperless does not care about the scanner brand; it watches a folder [13]. Three decisions matter more than the software. First, the scanner: look for double-sided scanning in one pass, a sheet feeder, and a network destination (SMB version 2 or newer, FTP or SFTP). Second, the OCR language: the default is English, so set deu+eng for German letters [2]. Third, the backup: use the built-in document_exporter, copy its output offsite, and rehearse the restore on a second machine, because an export only imports into the same version and an empty installation [3].

How it works

1. What you are building. Paperless has a consumer that watches a folder and a web server for the interface [5]. With the official PostgreSQL compose file you get three containers: a Valkey broker, PostgreSQL 18, and the Paperless web server, which also contains the consumer and listens on port 8000 [10]. The docs recommend PostgreSQL for new installations [1]. They also describe a script that does the setup interactively and warn you to read it before piping it into a shell [1]. Paperless runs on Linux only [1]. We found no RAM or CPU minimum in the setup docs, so we call it unconfirmed. The docs do say it runs on a Raspberry Pi, with tuning advice such as OCR of the first page only [1].
2. Version and image tag. The latest release we found on 25 Oct 2026 is v3.3.4 from 22 Oct 2026, a security maintenance release [9]. Version 3 has breaking changes. You can only upgrade to it from 2.20.15, PAPERLESS_SECRET_KEY is now required, the consumer settings were renamed, and duplicates are no longer rejected by default [4]. The official compose files use image: ...:latest [10]. The docs describe pinning to a release series [3]. A feature request in the project's discussions says the images come with minor and patch tags but no major tags such as 3, and a maintainer answers that offering only feature-release tags is deliberate [12]. We pin to a full version such as 3.3.4. We could not read the registry's tag list, so run docker pull ghcr.io/paperless-ngx/paperless-ngx:3.3.4 once to confirm the tag exists.
3. Scanner types, in general. Four kinds work. (a) A sheet-fed desktop scanner with a feeder and a touchscreen that saves to a network folder. (b) A multifunction printer with a feeder and scan-to-folder. (c) A scanner that works only through a computer; the Paperless wiki lists one such model as USB only, so it needs a PC in the chain [13]. (d) A phone app that uploads by FTP, SMB, WebDAV or the API; the wiki lists several [13]. Our assessment: a sheet-fed scanner with its own network destination gives the least friction, because the paper goes in and the file arrives without a computer.
4. Criteria instead of a winner. Check these on the data sheet, not on the box. Double-sided scanning in a single pass; if your scanner only does one side, Paperless can merge two passes (odd pages, then the reversed even pages) when you drop them into a double-sided subfolder, but that feature is off by default and you must create the folder yourself [6]. The feeder capacity. A network destination that you can use: the wiki's table has columns for FTP, SFTP, NFS, SMB, SMTP, WebDAV and API upload [13]. The SMB version the device speaks. The way the device names files and builds multi-page PDFs. Paperless does OCR itself, so you do not need a scanner that makes searchable PDFs [2].
5. Two examples with manufacturer data, not recommendations. Brother's US page for the ADS-1700W lists duplex scanning, a 20-page feeder, up to 25 pages (50 images) per minute, and scan to FTP and to a network folder, worded as "Network Folder (CIFS - Windows only)" [14]. Its support page describes a network profile with a folder path, a user name and password, a 2-sided scan option, a skip-blank-page option, and a reminder that the device's clock must be set [15]. Epson's user guide for the ES-C380W says it scans to a network folder (SMB), FTP/FTPS or WebDAV, and that you must create the shared folder first [16]. Its US data sheet lists a one-pass duplex scanner with a 20-sheet feeder [17]. Neither source we retrieved names the SMB version, so ask the vendor or test with your share before you keep the device. The Paperless wiki lists both models among its user recommendations, which is a user report, not a test [13]. We have not used either scanner. Check the regional data sheet, because these are US pages.
6. The SMBv1 trap. The wiki notes that older Canon models can scan only to SMBv1 shares, which modern systems and NAS devices disable by default, and it suggests a small SMB1 proxy instead of enabling SMBv1 on your main storage [13]. Samba has had SMB1 off by default since 4.11.0, and the release notes say that Microsoft no longer installs SMB1 support in recent releases [18]. If a scanner needs SMB1, choose another scanner or isolate the workaround. Do not weaken the server that holds your documents.
7. Other scan-to-folder traps. The wiki reports that some Canon multifunction devices close and reopen the file after every page, and recommends tuning the polling values, with 180 seconds as a starting point because of the device's three-minute timeout [13]. That advice predates Paperless v3, which renamed the consumer delay settings [4], so look up the current names in the configuration page [2]. Some scanners need a firmware or software version for SMB; the wiki names one ScanSnap model that requires a minimum firmware [13]. If the consumption folder itself sits on NFS or SMB, native file notifications may not work, and you must set PAPERLESS_CONSUMER_POLLING_INTERVAL to a positive number of seconds [1][2][7].
8. The consumption folder. Treat it as an inbox. Files you drop there are re-created inside Paperless and removed from the folder [5][8]. The docs suggest an FTP server or a Samba share on the host for scanners that push files [5]. Bind-mount ./consume in the compose file to a host folder, and set USERMAP_UID and USERMAP_GID to your host user so both sides can write [1][11]. With PAPERLESS_CONSUMER_RECURSIVE=true Paperless also reads subfolders, and PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true turns folder names into tags [2]. Since v3, a duplicate is consumed and flagged unless you set PAPERLESS_CONSUMER_DELETE_DUPLICATES=true [4][5].
9. OCR languages. Paperless uses Tesseract through OCRmyPDF. PAPERLESS_OCR_LANGUAGE takes three-letter codes, can combine languages such as deu+eng, and defaults to eng. Several languages cost more CPU time [2]. The container ships English, German, Italian, Spanish and French; others need PAPERLESS_OCR_LANGUAGES, which does not work in rootless containers [1][2][11]. The date parser uses a different format with two-letter codes such as de+en, and infers its languages from the OCR setting if you leave it empty [2]. The OCR mode defaults to auto, which skips OCR where a document already has embedded text. redo re-runs OCR for scanners whose own text layer is poor [2].
10. Keep it off the internet. Our recommendation is LAN or VPN only, with no port forwarded. The sample environment file says PAPERLESS_URL is needed when you expose Paperless on a public domain and mentions a reverse proxy [11]; the reverse proxy guide under Related pages explains the setup. The docs suggest a separate everyday account instead of working as superuser [1].
11. What the exporter does. document_exporter writes your documents, thumbnails and a manifest.json with the database contents to a folder, and it updates an existing export incrementally [3]. In the compose setup, the target ../export is the host folder ./export [3][10]. Useful options: -d also removes files of deleted documents, -z writes a zip, --data-only exports only the database, and --passphrase encrypts certain fields, with the warning that a lost passphrase makes the export unimportable [3]. API tokens are not exported [3]. The docs advise making backups when Paperless is not consuming [3]. In a cron job, use docker compose exec -T webserver document_exporter ../export [3].
12. What the exporter does not do. An export imports only into the same Paperless version [3]. The importer wants a completely empty installation [3]. The alternative is to back up the Docker volumes: the docs name paperless_media, paperless_data and paperless_pgdata [3]. Our assessment: do the export as the main backup, and copy the export folder with a tool that does versions and encryption, which our restic and Borg guide covers under Related pages. A copy that sits next to the server is one copy. The 3-2-1 guide explains why you need more.
13. Retention is not our topic. Paperless's recommended workflow keeps a paper original only for documents you need in physical form, such as contracts and certificates, and numbers those with an archive serial number [5]. Which documents you may discard, and for how long you must keep any, is a legal and tax question. Ask a tax adviser or the competent authority. We make no statement.

A homelab example

This is a generic setup for your own Linux server, not a report on ours. We make no statement about Paperless-ngx or scanners in the Bytearium homelab. Assume a folder /srv/paperless on the host.

Fetch the three files of release v3.3.4 that the docs ask for [1]:

mkdir -p /srv/paperless/consume /srv/paperless/export && cd /srv/paperless
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/v3.3.4/docker/compose/docker-compose.postgres.yml
curl -fsSLo docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/v3.3.4/docker/compose/docker-compose.env
curl -fsSLo .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/v3.3.4/docker/compose/.env

In docker-compose.yml, change image: ghcr.io/paperless-ngx/paperless-ngx:latest to image: ghcr.io/paperless-ngx/paperless-ngx:3.3.4 [10]. In docker-compose.env, set at least:

USERMAP_UID=1000
USERMAP_GID=1000
PAPERLESS_SECRET_KEY=<output of: python3 -c "import secrets; print(secrets.token_urlsafe(64))">
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
PAPERLESS_CONSUMER_RECURSIVE=true

The key command comes from the env file's comment [11]. Then run docker compose pull and docker compose up -d. Open http://<server>:8000 from inside your network and create the superuser when asked [1].

Make the scanner write into /srv/paperless/consume, for example through a Samba share on the host that the scanner can reach. Configure a profile on the scanner: PDF, 2-sided on, skip blank pages on, and the share path with a dedicated user that can only write there. Scan three test letters and check text search, the language of the OCR and the dates Paperless extracts.

Backup, as a nightly job on the host:

cd /srv/paperless && docker compose exec -T webserver document_exporter ../export --no-progress-bar

Then copy /srv/paperless/export to a second disk and offsite with restic or Borg. Keep docker-compose.env (it contains the secret key) and any export passphrase in a place that is neither the server nor the same backup repository.

Rehearse the restore: on a second machine, create the same folder, use the same image tag, run docker compose up -d, copy the export folder into ./export, and run docker compose exec webserver document_importer ../export [3]. Search for three documents you know, and open them. Then generate new API tokens, because exports do not contain them [3].

Checklist

• Check the data sheet for one-pass duplex scanning, feeder capacity and a network destination you can use.
• Ask the vendor or test which SMB version the scanner speaks, and never enable SMB1 on the machine that holds your documents.
• Set PAPERLESS_OCR_LANGUAGE to deu+eng or your own mix, and set PAPERLESS_SECRET_KEY before the first start.
• Pin the image tag to a full version and confirm it with a single docker pull.
• Mount ./consume as a bind mount, set USERMAP_UID and USERMAP_GID, and enable polling if the folder sits on a network share.
• Keep Paperless reachable only from the LAN or a VPN.
• Run document_exporter on a schedule, and copy the export offsite with versions and encryption.
• Store the secret key and the export passphrase apart from the server and the backup repository.
• Restore into an empty second installation of the same version, and write down the date and the result.
• Ask a tax adviser how long you must keep which documents before you throw away any paper.