paperless-ngx.readthedocs.io

What is Paperless-ngx?

Paperless-ngx is a self-hosted document management system: you feed it scans and PDFs, it indexes their contents with OCR, and you search and organize them through a web interface instead of filing cabinets or folders. The page you supplied is only a redirect notice — the documentation has moved — but it confirms the project's scope through its table of contents: setup, configuration, scanners and software, administration, advanced topics, usage, troubleshooting, a changelog, and a REST API.

What that means in practice

• OCR and full-text search. Documents become searchable by their contents, not just filenames, which is the main reason people adopt it over a shared drive.
• Tags, correspondents and document types. Instead of a rigid folder tree, you attach metadata, so one document can belong to several categories at once.
• A web app plus an API. The REST API matters if you want scripts, mobile apps or home-automation workflows to file documents automatically.
• Self-hosting. You run it on your own hardware, so storage, backups and access control are your responsibility.

Who it suits

A household drowning in bills, contracts and medical letters; a small office that wants searchable archives without a cloud subscription; or a tinkerer who already runs a home server and wants documents to stay on their own disk. It suits people comfortable with Docker-style deployment and periodic backups. It is a poor fit if you want a zero-maintenance hosted service or need heavy collaborative editing and approval workflows.

A concrete scenario

You scan a stack of insurance letters to a watched folder. Paperless-ngx consumes them, runs OCR, and you later search "deductible" to pull up the right letter, tagging it with a correspondent and a document type. From there the REST API could, for example, push a notification or mirror metadata into another system.

Next step

Start at the project's current documentation to check installation options and hardware expectations before committing. Compare it with Mayan EDMS if you need heavier workflow and access-control features, or Docspell if you want a similar self-hosted approach with a different data model. The deciding question is usually how much control you want over scanning, OCR and retention versus how much setup and upkeep you are willing to take on.

How do I install and set up Paperless-ngx?

Paperless-ngx is a self-hosted document management system: it watches a folder for scanned files, runs OCR, and makes the results searchable through a web interface. Installation is not a single click; it is a small server deployment you maintain yourself.

The documentation you are looking at is a redirect page — the project's docs moved to a newer site, so treat this page as a signpost rather than the current install guide. For the up-to-date instructions, use Paperless-ngx documentation and the code repository at GitHub.

What setup actually involves

1. Pick a host. A always-on machine — a home server, NAS, Raspberry Pi, or a small VPS — running Linux with Docker and Docker Compose installed. Paperless-ngx is normally deployed as a set of containers (web app, database, Redis, and a document consumer).
2. Get the compose configuration. The official docs provide a docker-compose.yml plus an environment file. You download these, then edit the environment file before starting anything.
3. Set the essentials in that environment file. At minimum: a secret key, the database password, your timezone, the OCR language, and the hostname/port you will reach it on. Paths for the consume folder and media folder also matter — the consume folder is where you drop scans for automatic import.
4. Start the stack. docker compose up -d from the directory holding the compose file. First start initialises the database and takes a minute or two.
5. Create your admin account. Run the createsuperuser management command inside the web container.
6. Log in and configure. Add correspondents, document types and tags, set your storage paths, and decide whether to enable email fetching or a scanner integration.

Docker Compose vs. bare-metal

A practical starting scenario

You have a box of paper to digitise and a flatbed scanner. Set up the Docker stack, point the scanner's output at the consume folder (or use a network scan-to-folder target), and drop in a test batch of ten pages. Check that OCR text is searchable and that the auto-assigned date looks right before you commit to scanning hundreds of documents — tuning tags and matching rules is far easier on a small sample.

Before you start, decide

• Where the data lives. Back up the database, media folder and consume folder together; a backup of only the database is useless without the PDFs.
• How documents arrive. Manual upload, watched folder, email, or scanner — the docs cover each, and mixing them is fine.
• Whether you want exposed access. If you plan to reach it from outside your home network, put it behind a reverse proxy with TLS rather than opening the app port directly.

If you are not comfortable maintaining a Linux server, that is the real barrier here, not the installation commands themselves.

Which scanners and software work best with Paperless-ngx?

Paperless-ngx does not require a specific scanner brand. It works with documents you can get into a folder or send over a network, so the "best" scanner is usually the one that produces clean, searchable PDFs with the least manual effort.

The documentation itself groups Scanners & Software as a topic, which tells you the project expects you to pair it with your own capture setup rather than a bundled device.

What tends to work well

• Scanners with a document feeder and duplex scanning. For multi-page bills, contracts and receipts, an automatic document feeder that scans both sides in one pass saves the most time. Flatbed-only scanners are fine for occasional single pages but slow for batches.
• Scanners that output PDF directly, especially searchable PDF or PDF/A. This avoids a separate conversion step before Paperless-ngx consumes the file.
• Network or email-capable scanners. If the device can save to an SMB share, FTP folder, or send email, you can often drop documents straight into a watched folder or inbox without touching a computer.
• Mobile scanning apps for receipts and one-off pages. These are convenient for capture on the go, but check that the exported PDF is legible and not heavily compressed.
• OCR tooling such as Tesseract, which is the common engine behind many document pipelines. Good OCR matters more than scanner brand for search quality.

Trade-offs to weigh

A practical next step

Before buying anything, test your current scanner: scan a typical document, confirm the PDF has a text layer, then drop it into your Paperless-ngx consumption folder and check whether the title, date and tags are detected correctly. If that works, your scanner is already a good fit.

For setup details and supported workflows, start with the official documentation at Paperless-ngx documentation. If you want to compare OCR engines or scanning utilities, look at Tesseract OCR and Read the Docs for related project docs.

How can I use the Paperless-ngx REST API for automation?

The Paperless-ngx REST API lets you drive document capture and retrieval from scripts, cron jobs and integrations rather than clicking through the web UI. The official documentation is at Paperless-ngx documentation; the REST API has its own section there, and the project's source and issue tracker live at GitHub.

Typical automation patterns

• Push documents in: upload a scan or PDF from a watched folder, email gateway or line-of-business app, with tags and correspondents set in the same request.
• Pull metadata out: list documents matching a query (date range, tag, correspondent) and sync titles, dates and tags into a spreadsheet, wiki or database.
• Bulk housekeeping: apply or remove tags, move documents between storage paths, or trigger re-processing after you change OCR settings.
• Build a front end: the API is what the web UI itself talks to, so custom dashboards and mobile clients are realistic projects.

What to check first

Authentication is the main gate. Paperless-ngx supports token-based auth, so generate a token for a dedicated automation user and keep it in an environment variable or secret store rather than in the script. Then confirm the API version you are targeting, since endpoints and payload fields can change between releases; the changelog in the docs is the place to look before upgrading.

A concrete starting scenario

A small office scans invoices to a network folder. A nightly script uploads each new PDF via the API, attaches the tag incoming and the correspondent guessed from the filename, then queries the API for documents tagged incoming older than seven days and posts a summary to a chat channel. If a document fails to upload, the script logs the HTTP status and leaves the file in place for a retry.

Trade-offs

The API is powerful but unglamorous: you own error handling, retries and rate limiting, and you must keep the token secure. For simple "watch a folder" needs, Paperless-ngx's built-in consumption directory may be less work than writing API code. Choose the API when you need conditional logic, cross-system sync or a custom interface; choose the built-in scanner and consumption workflow when you just want documents in.

Next step: open the REST API page in the documentation, find the authentication section, and make one read-only request (for example, listing documents) with curl before writing any upload logic.

What are the common troubleshooting steps for Paperless-ngx?

The Paperless-ngx documentation page you're looking at is a redirect notice: it states the docs "have permanently moved" and that you'll be redirected shortly. So the troubleshooting content you want lives on the current docs site, not this 1.10.0 snapshot. For Paperless-ngx specifically, start at Paperless-ngx documentation, which is the project's official docs home, and use its Troubleshooting and FAQ sections.

For a reader running Paperless-ngx at home, most troubleshooting falls into a few buckets. Work through them in this order:

• Check the logs first. The consumer (document ingestion) and the web server log separately. A document that never appears is usually a consumer error, not a UI problem.
• Confirm the document was actually consumed. Look at the task/queue status and whether the file was moved into the consumption directory and then archived. Files sitting in the consume folder untouched often point to permissions or a stopped service.
• Verify permissions and ownership. The container user or service account needs read access to the consume directory and write access to the media, data and export directories. Permission mismatches are a very common cause of silent failures.
• Check OCR and language settings. If text isn't searchable, the OCR language may not match the document, or the OCR tooling may be missing or misconfigured.
• Look at database and broker connectivity. If the web UI loads but nothing processes, the queue/broker or database connection is often the culprit.
• Reproduce with one file. Drop a single simple PDF or image into the consume directory and watch the logs end to end; this isolates whether the issue is format-specific or systemic.

A practical decision rule: if the web UI is reachable but new documents don't appear, the problem is almost always in the consumer/queue or file permissions. If the UI itself won't load, focus on the web service, database and reverse proxy.

As a next step, open the current official docs, search the Troubleshooting and FAQ pages for your exact error text, and check the project's issue tracker for known bugs in your version. For version-specific behaviour, the release notes and changelog are the fastest way to see whether an upgrade already fixed it.

How does Paperless-ngx handle document storage and backup?

Paperless-ngx stores documents as ordinary files on disk, not inside a proprietary database. A scanner or watch folder feeds PDFs or images in; Paperless-ngx runs OCR, extracts metadata, and files the original plus a searchable archived copy in a media directory. The database (PostgreSQL or SQLite) holds the index — correspondents, tags, document types, dates and full-text search data — while the actual documents live in the media folder. That split matters: losing the database costs you the index and metadata, but the files themselves remain readable.

Backup implications

Because of that architecture, a complete backup needs three things:

• The media directory (originals and archived/OCR'd versions)
• The database (metadata and search index)
• The configuration (settings, secrets, environment files)

Backing up only the media folder preserves your documents but loses tags, correspondents and search. Backing up only the database preserves the index but points at files that no longer exist. Restoring one without the other produces a half-working instance.

Practical approaches

For a small home setup, a scheduled rsync or restic/borg job covering the media directory, a database dump, and the config directory is usually enough. For anything larger, run the database dump as a deliberate step rather than copying live database files, since copying an active database can capture an inconsistent state. The official docs at Paperless-ngx documentation cover setup, configuration and administration, and the project source and issue tracker are at GitHub.

Choosing your approach

The trade-off is between simplicity and completeness: file-level backups are easy to inspect and restore by hand, while database dumps are smaller and consistent but useless without the media folder. Whichever you choose, test a restore into a scratch instance before you need it — an untested backup is a guess.