Paperless-ngx

Paperless-ngx is a community-maintained document management system that transforms physical documents into a fully searchable digital archive. Developed as the official successor to the original Paperless and Paperless-ng projects, it brings together OCR processing, machine learning classification, and a polished Angular web interface to give individuals and small teams complete control over their documents without relying on cloud services.

At its core, Paperless-ngx processes incoming documents — whether scanned, emailed, or dropped into a watch folder — through a pipeline that extracts text via Tesseract OCR and OCRmyPDF, classifies them using trainable ML models or LLM-powered AI, and stores them in a structured, fully searchable archive. Documents are automatically tagged, assigned to correspondents and document types, and can be routed through configurable workflows that trigger on ingestion, scheduling, or custom conditions.

Version 3.0 marks a major milestone for the project, introducing deep AI integration via LlamaIndex with support for Ollama, OpenAI-compatible APIs, and HuggingFace sentence transformers for semantic search and RAG-based document classification. The system now supports vector embeddings for similarity search alongside the existing full-text Tantivy engine, giving users both keyword precision and semantic recall.

With multiple Docker Compose configurations covering PostgreSQL, MariaDB, and SQLite backends, plus optional Apache Tika integration for extended format support, Paperless-ngx scales from a Raspberry Pi home setup to a multi-user team deployment — all without any licensing fees or usage limits.

What You Get

• OCR-powered text extraction - Processes PDFs, images, and scanned documents through Tesseract and OCRmyPDF to extract full text, making every document searchable by content regardless of its original format.
• AI-assisted document classification - Trains on your existing archive to automatically suggest and assign tags, document types, correspondents, and titles — with optional LLM backends (Ollama or OpenAI-compatible) for RAG-enhanced classification.
• Configurable workflow automation - Triggers actions (tag assignment, ownership, custom field population, webhooks) based on document ingestion events, scheduled runs, or matching conditions — all defined through the web UI.
• Dual search engine - Combines a Tantivy-powered full-text index for keyword precision with optional vector embeddings using FAISS and sentence transformers for semantic similarity search.
• Multi-source document ingestion - Accepts documents via a web upload, REST API, watch folders, IMAP email polling, or barcode-triggered splitting — handling batch processing from physical scanners to email inboxes.
• In-browser PDF editor - Allows page reordering, rotation, deletion, and document splitting/merging directly in the web interface without requiring external tools.
• Fine-grained permission system - Supports multi-user deployments with per-object ownership, group-based permissions via Django Guardian, and SSO integration through django-allauth with MFA support.
• Structured custom fields - Lets users define custom metadata fields per document type, enabling domain-specific data capture beyond built-in tags and correspondents.

Common Use Cases

• Home paperless office - A household digitizes all incoming mail, utility bills, and financial statements via a desktop scanner into a watch folder, letting Paperless-ngx auto-classify and tag documents for instant retrieval at tax time.
• Small business invoice management - A freelancer or small team configures IMAP polling to pull PDF invoices from a dedicated email inbox, automatically assign them to the correct correspondent, and route them to the accounting folder via workflows.
• Legal and medical record archiving - A paralegal or clinic administrator ingests paper files through barcode-sheet-triggered batch scanning, ensuring each document lands in the correct patient or case folder without manual sorting.
• Compliance and audit trail - A regulated business enables the audit log module to capture every document access and modification event, supporting compliance requirements with a tamper-evident record stored in the local database.
• Multi-user team document hub - A small organization deploys Paperless-ngx on a shared server, assigns per-user and per-group document ownership, and uses custom fields to track approval status and document lifecycle stages.
• Hybrid AI-assisted archiving - A power user connects a local Ollama instance to Paperless-ngx’s AI backend, enabling LLM-powered title generation, tag suggestions based on document content, and semantic search across thousands of archived files.

Under The Hood

Architecture Paperless-ngx is built as a layered Django monolith with clearly separated ingestion, processing, storage, and presentation concerns. Documents flow through a plugin-based consumer pipeline — each plugin handles a discrete processing stage (barcode detection, OCR, AI classification, workflow execution) and can be extended via Python entry points registered in pyproject.toml. The background processing tier uses Celery workers backed by Redis for task queuing, with Channels and WebSockets pushing real-time progress updates to the Angular frontend. REST API boundaries between frontend and backend are well-defined through Django REST Framework with drf-spectacular providing OpenAPI schema generation. The search subsystem runs two parallel indexes: a Tantivy full-text engine for keyword search and an optional FAISS vector store for semantic similarity — both are updated asynchronously by Celery tasks, keeping ingestion throughput independent of index rebuild time.

Tech Stack The backend is Python 3.11–3.14 on Django 5.2 with Django REST Framework, Django Channels for WebSocket support, and Celery 5 with Redis as the broker and cache. Database options include PostgreSQL, MariaDB, and SQLite, all accessed via Django ORM. The AI stack is built on LlamaIndex with pluggable embedding backends — HuggingFace sentence-transformers for local operation, or Ollama and OpenAI-compatible APIs for LLM-backed classification and chat. OCR is handled by OCRmyPDF wrapping Tesseract, with Apache Tika available for extended format parsing. The Angular 18 frontend uses TypeScript throughout, built with pnpm and served as a static SPA. Deployment is containerized with multi-stage Docker builds using s6-overlay for process supervision and Granian with uvloop for the ASGI application server.

Code Quality The project maintains extensive automated test coverage with over fourteen hundred backend test functions across sixty-four test modules using pytest, plus Jasmine and Karma suites on the Angular side. Code quality tooling includes Ruff for Python linting and formatting, ESLint and Prettier for TypeScript, and a comprehensive CI pipeline on GitHub Actions that runs tests, coverage reporting via Codecov, and container image builds on every pull request. Error handling is explicit throughout — the consumer pipeline captures and logs exceptions per plugin stage without silently swallowing failures, and the AI client includes a system prompt boundary to prevent prompt injection from untrusted document content. Django’s type-annotated models combined with TypeScript on the frontend provide strong typing end-to-end.

What Makes It Unique Paperless-ngx’s combination of a plugin-extensible consumer pipeline with a dual-index search architecture sets it apart from simpler self-hosted DMS solutions. The ability to connect local Ollama models for fully offline AI classification — no API keys, no data leaving the network — while also supporting standard OpenAI-compatible endpoints gives it unusual flexibility for privacy-conscious deployments. The workflow engine, built on Django ORM annotations, lets users define arbitrarily complex document routing rules through a GUI without writing code. Document version tracking with soft-delete support and a full audit log make it suitable for compliance scenarios most hobbyist DMS tools ignore entirely.

Self-Hosting

Paperless-ngx is released under the GNU General Public License v3.0, a strong copyleft license. For self-hosters, the GPL-3.0 means you can run it commercially, modify it, and distribute modified versions — but if you distribute software that incorporates Paperless-ngx, you must release that derivative under the same GPL-3.0 terms. For the vast majority of self-hosting scenarios (running it for your own organization or household), the copyleft obligation never triggers, making it effectively free to use without restriction.

Running Paperless-ngx yourself requires meaningful infrastructure investment. The recommended deployment uses Docker Compose with separate containers for the web application, Celery worker, Redis broker, and a database server (PostgreSQL is recommended for production). Storage requirements grow with your document volume — OCR’d PDFs with thumbnail generation can consume substantial disk space. You are responsible for maintaining the Docker images, applying security patches (the project releases frequently, often in response to CVEs), managing database backups, and ensuring Redis and the background workers remain available. The AI features add further complexity if you run a local Ollama instance, which requires GPU or sufficient CPU/RAM to be practical.

There is no official hosted or managed version of Paperless-ngx — the project is entirely community-run with no commercial entity behind it. This means no SLAs, no enterprise support contracts, and no managed upgrade path. Support is available through GitHub Discussions, a Matrix community channel, and an active contributor base of hundreds of volunteers. Compared to commercial document management services, you give up automatic updates, offsite backup management, and vendor-provided data recovery — but you gain complete data sovereignty, no per-user pricing, and the ability to run fully air-gapped with local LLM backends.