Setting Up Paperless-ngx With Docker Compose: Consume Folder, OCR Languages and Backups
Raymond Foster
November 21, 2026
You have a drawer of letters, a scanner that can save PDFs to a network folder, and a home server already running Docker. Paperless-ngx turns that pile into a searchable archive: it OCRs every page, files the original and an archival PDF, and suggests tags and correspondents. The official Docker Compose route gets it running in a few minutes, but the defaults leave a few decisions to you: which database, which OCR languages, how files reach the consume folder, and how you will get your documents back if the disk dies. This guide walks through those decisions using the current Paperless-ngx documentation and compose files.
Everything here reflects Paperless-ngx 3.x. Version 3.0 shipped in July 2026 and changed several settings, so if you are following an older tutorial, some variable names below will look different. The latest release at the time of writing is v3.5.1.
Step 1: Pick one of the official compose files
The project keeps its compose templates in the docker/compose directory of the paperless-ngx GitHub repository. There are six that matter for a normal install, combining three database options with an optional office-document stack:
docker-compose.postgres.ymlanddocker-compose.postgres-tika.ymldocker-compose.mariadb.ymlanddocker-compose.mariadb-tika.ymldocker-compose.sqlite.ymlanddocker-compose.sqlite-tika.yml
The setup docs recommend PostgreSQL for new installations. SQLite works and keeps the stack smaller, but PostgreSQL is the documented default path and the one most people will be able to help you with. The -tika variants add two extra containers: Apache Tika, which extracts text and metadata, and Gotenberg, which converts Word, Excel, PowerPoint, LibreOffice files and emails to PDF. If you only ever feed Paperless scanned PDFs and images, you can skip them. If you want to drop a .docx or an .eml file into the inbox, pick a Tika file.
Every variant also includes a broker container. Paperless-ngx needs a Redis-compatible message broker for its task queue, and the current compose files use the valkey/valkey:9-alpine image for it, wired in through PAPERLESS_REDIS: redis://broker:6379. The Postgres file currently pins postgres:18, and the Tika file pins specific Gotenberg and Tika image versions. The Paperless image itself is ghcr.io/paperless-ngx/paperless-ngx:latest.
Make a directory on the server, for example /opt/paperless, and save three files there:
- Your chosen compose file, renamed to
docker-compose.yml. docker-compose.env, which holds the Paperless settings..env, which currently only setsCOMPOSE_PROJECT_NAME=paperless. That project name is why the Docker volumes end up namedpaperless_media,paperless_dataand so on.
The docs also offer an interactive installation script that does all of this for you; the manual route gives you a clearer picture of what you are running.
Step 2: Decide where the documents live on disk
Open docker-compose.yml and look at the webserver service’s volumes. By default you get:
data:/usr/src/paperless/data: a Docker volume for the search index, classifier and (with SQLite) the database.media:/usr/src/paperless/media: a Docker volume holding your actual documents, originals and archive versions../export:/usr/src/paperless/export: a folder next to the compose file for exporter output../consume:/usr/src/paperless/consume: the inbox folder Paperless watches.
The docs suggest changing the part before the colon if you want bind mounts instead, for example pointing consume at a folder your scanner can write to. Many people also bind-mount media to a dataset on a NAS pool so the documents are easy to find and snapshot. Whatever you choose, never change these paths later without care: the administration docs warn that changing paths during migrations risks data loss.
The default web port is 8000. If something else already uses it, change the host side of the mapping, such as 8010:8000.
Step 3: Fill in docker-compose.env
This file is where most of the setup happens. The shipped template has commented examples; these are the settings worth setting deliberately.
PAPERLESS_SECRET_KEY is now mandatory
Since v3.0, Paperless refuses to start without PAPERLESS_SECRET_KEY. It signs session tokens and other sensitive data. The template ships with PAPERLESS_SECRET_KEY=change-me; replace it with a long random value. The docs suggest generating one with python3 -c "import secrets; print(secrets.token_urlsafe(64))". You never need to type it again, but keep it with your backup notes, because changing it invalidates existing sessions and signed tokens.
PAPERLESS_URL for reverse proxies
If you will reach Paperless through a domain name behind a reverse proxy, set PAPERLESS_URL to the full public URL without a trailing slash, for example PAPERLESS_URL=https://paperless.example.com. Per the configuration docs, this one setting fills in the allowed hosts, CORS and CSRF trusted origins. It cannot contain a path, even if you serve Paperless under a subpath. If you only use the LAN IP and port, you can leave it unset.
Time zone and file ownership
PAPERLESS_TIME_ZONE defaults to UTC. Set it to your zone, such as America/New_York, so document dates and scheduled tasks line up with your clock.
USERMAP_UID and USERMAP_GID control which user the container runs as internally. Set them to your host user’s IDs (find them with id -u and id -g) so both you and the container can write to the consume folder. If your IDs are 1000, the default works as is. If you prefer a truly rootless container, the setup docs describe setting user: '1000:1000' on the webserver service instead, without the USERMAP variables. That mode cannot install extra OCR languages, which leads to the next setting.

Step 4: Set the OCR languages your documents actually use
Two similarly named variables do different jobs, and mixing them up is a common source of poor OCR.
PAPERLESS_OCR_LANGUAGE(singular) is the language Tesseract uses when reading your documents. It takes three-letter Tesseract codes, and you can combine them with a plus sign, for examplePAPERLESS_OCR_LANGUAGE=deu+eng. The docs note that Tesseract uses much more CPU with multiple languages, so only list what you need. The default is English.PAPERLESS_OCR_LANGUAGES(plural) installs additional language packs into the container at startup. The image ships with English, German, Italian, Spanish and French. For anything else, list the packages space-separated, for examplePAPERLESS_OCR_LANGUAGES=tur ces. The docs warn that Debian package names do not always match Tesseract codes: Traditional Chinese ischi_traas an OCR language butchi-traas a package.
A Polish household, for example, would add pol to the plural variable and set the singular one to pol or pol+eng. Set both before the first start so the very first documents are read correctly.
The OCR behavior itself is controlled by PAPERLESS_OCR_MODE. The default, auto, checks whether a PDF already has embedded text and skips OCR when it does, which suits a mix of born-digital PDFs and scans. Version 3.0 redesigned the OCR and archive-generation settings and removed some older ones; Paperless logs a startup warning if a removed variable is still set, so read the container log after your first start.
Step 5: Pull, start and create the admin account
From the directory with your files, run:
docker compose pullto fetch the images.docker compose up -dto create and start the containers.
Then open http://your-server:8000. On a fresh install, the web interface prompts you to create the first superuser account. If you need another superuser later, or you are locked out, run docker compose exec webserver createsuperuser while the stack is running. For automated deployments, the configuration docs also offer PAPERLESS_ADMIN_USER and PAPERLESS_ADMIN_PASSWORD, which create a superuser at startup.
The docs point out that superusers can see every document and object, and suggest creating a separate regular account for daily use. If several family members will share the instance, set up users, groups and default permissions now, before documents start arriving.
Step 6: Get documents into the consume folder
Paperless watches the consume folder, processes anything that appears, and then removes the file from the folder after storing it in its own media structure. Treat the folder as an inbox, not storage.
From a network scanner
The usage docs suggest the usual approaches for getting scanner output onto the server: an FTP server, or a Samba (SMB) share that points at the consume directory. Most office scanners and multifunction printers can scan to an SMB folder. Give the scanner its own account with write access only to that share.
When the consume folder is on NFS or SMB
If the consume folder itself lives on a network share mounted into the container, Paperless may never notice new files, because NFS and SMB do not reliably deliver filesystem notifications. Set PAPERLESS_CONSUMER_POLLING_INTERVAL to a number of seconds, such as PAPERLESS_CONSUMER_POLLING_INTERVAL=30, to switch from notifications to polling. In v3 this replaced the older PAPERLESS_CONSUMER_POLLING setting. If files on slow storage get picked up before the scanner finishes writing them, raise PAPERLESS_CONSUMER_STABILITY_DELAY, which sets how long a file must stay unchanged before consumption starts.
Subfolders as tags
Two settings let you sort documents before they arrive. With PAPERLESS_CONSUMER_RECURSIVE=true, Paperless also picks up files in subfolders. Add PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true, and a file dropped into consume/car/ gets the tag “car.”
Duplicates behave differently in v3
Version 3.0 stopped rejecting duplicate documents by default; it now consumes them and flags them in the UI. If you want the old behavior, where a duplicate is deleted from the consume folder without being imported, set PAPERLESS_CONSUMER_DELETE_DUPLICATES=true.
Email ingestion
Mail accounts and rules are configured in the web UI under Settings, Mail, not in the env file. You add an IMAP account, then rules that choose a folder, filters and maximum age, and an action for processed mail: delete, mark as read, flag, move to a folder or add a custom IMAP keyword. Paperless only acts on mails it consumed documents from, and the actions exist so the same message is never imported twice. If you are still weighing Paperless against a general file cloud for this job, see Paperless-ngx vs Nextcloud for scanned household documents.

Step 7: Back up with document_exporter, not just the volumes
The administration docs list two backup approaches for Docker installs, and it is worth using both.
The first is the document exporter. It writes all documents, thumbnails, a manifest.json with database contents such as tags and correspondents, and your settings into a folder. With the stock compose file, the target inside the container is ../export, which maps to the export folder next to your compose file. For a scheduled job, the docs recommend the -T flag so cron does not complain about a missing TTY:
docker compose exec -T webserver document_exporter ../export
Useful options from the docs:
- Running it again against the same folder updates the existing export, copying only changed and new files, so incremental copies with rsync or a backup tool work well.
-dremoves files from the export that no longer belong, such as deleted documents.-ccompares checksums instead of size and modification time; slower but stricter.-zwrites a single zip file instead of a folder.--no-progress-barkeeps cron output quiet.--passphraseencrypts certain sensitive fields in the export; without the passphrase, the export cannot be imported.
Two caveats from the docs: the export does not include API tokens, so apps will need new tokens after a restore, and an export should be imported into the same Paperless version that created it, because it is an exact image of the database. Restore with document_importer against a completely empty installation.
The second approach is backing up the Docker volumes: paperless_media for documents, paperless_data for auxiliary data, and paperless_pgdata or paperless_dbdata for the database. Copying a live database directory can produce a broken backup, which is why the exporter, which goes through the application, is the safer primary copy. The broader pattern is covered in backups that restore empty databases and Docker Compose backup strategies for beginners.
Whatever you choose, send the export off the server, and test a restore into a throwaway instance at least once.
Updating Paperless-ngx without losing the archive
The compose files use the latest tag, which always points to the newest stable release. The documented update process is:
- Make sure nothing is being consumed, then run the exporter.
docker compose downdocker compose pulldocker compose upin the foreground, which also applies database migrations. Once it looks healthy, stop it with Ctrl+C and start again withdocker compose up -d.
If you would rather not jump major versions by surprise, pin the image to a release series, for example ghcr.io/paperless-ngx/paperless-ngx:3.5, and read the release notes before changing it.
If you are still on 2.x, the v3 migration guide applies. You must first update to v2.20.15, set PAPERLESS_SECRET_KEY, and, if you use PostgreSQL or MariaDB, add PAPERLESS_DBENGINE explicitly, since v3 no longer infers the engine from PAPERLESS_DBHOST. Consumer settings were renamed, consumer ignore patterns switched from fnmatch to regex, and the old document encryption support was removed, so encrypted installs must run decrypt_documents first. The current compose files already include the v3-style settings.
The optional AI features and what they send where
Paperless-ngx now includes official, optional LLM-backed features: AI-assisted suggestions, similar-document retrieval and a document chat. They are off by default and do not replace the built-in matching. Enabling them takes PAPERLESS_AI_ENABLED=true plus an LLM backend, either ollama running locally or an openai-like API. The docs warn plainly that enabling these features sends document content to whatever backend you configure, so a hosted provider means your documents leave your server. If you want them, point Paperless at a local Ollama instance.
For most households, the standard setup above is enough: PostgreSQL, the right OCR languages, a scanner writing to the consume share, and a nightly document_exporter run copied somewhere else.