paperless-ngx / paperless-ngx
A community-supported supercharged document management system: scan, index and archive all your documents
github.com/paperless-ngx/paperless-ngxIndexed at c50c6f5Up to date with upstream
About this codebase
Paperless-ngx is a document management system: it ingests physical documents (via mail/scanners and import paths), transforms them into searchable online archive records (documents + metadata + permissions), and exposes them through the paperless-ngx-ui for browsing, search, and actions—backed by async task processing and multiple evidence layers for matching and AI indexing. It’s used by people who want to keep, well, _less paper_: a user interacts with the web UI and an API client, while the backend processes consume events (including mail consumption and plugins), update stored evidence (indexes and vector stores), and return results to the UI.
Written by gpt-5.4-nano from the index
1,085 files and 8,940 symbols in 6 modules, led by TypeScript (431 files) and Python (410).
Code health
This codebase scores 8.1 out of 10 for code health, which we rate good. It also scores maintainability 8.6 and static performance 9.9 out of 10. The three are scored separately and never blended into one number. Risk is concentrated, as it usually is: 129 of 1,085 files are git hotspots, and they average 7.2 — which is where the fixes pay off most.
On the leaderboards:#4 of 44 Python repos
Do next
11 things worth doing this quarter.
Worth planning
Fix 206 broken references in
docs/configuration.mdThe document points readers and agents at paths this repository no longer has.
- broken references
- 206
- first
- advanced_usage.md#barcode-contents
Small effortFix 42 broken references in
docs/advanced_usage.mdThe document points readers and agents at paths this repository no longer has.
- broken references
- 42
- first
- administration.md#llm-index
Small effortFix 29 broken references in
docs/usage.mdThe document points readers and agents at paths this repository no longer has.
- broken references
- 29
- first
- administration.md#create-superuser
Small effort
Use paperless-ngx/paperless-ngx in your agent
Point Claude Code, Cursor, Codex or VS Code at this repository. Your agent gets the index this page is built from: cited answers, callers, history and health for any file.
https://api.repowise.dev/mcp/paperless-ngx/paperless-ngxOne command, run anywhere. Adds the server to your local Claude Code config.
Docsclaude mcp add --transport http repowise https://api.repowise.dev/mcp/paperless-ngx/paperless-ngx \ --header "Authorization: Bearer rw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
This repo is public, so anyone with a Repowise account and an API key can connect.
Try asking
- get_overview()
- get_answer("how is paperless-ngx put together?")
- get_why("why is paperless-ngx structured this way?")
Prefer local? pip install repowise && repowise init indexes your own checkout, no account needed.
Go deeper
- OverviewEverything the index found, what changed this week, commits and decisions.
- DocumentationModule-by-module documentation, 1,241 pages, 41 written by a model.
- ArchitectureDependency graph, layers and third-party dependencies.
- Code healthEvery file's score, the findings behind it, tests and refactoring plans.
- CommitsEach commit's effect on code health, with agent provenance.
- ContributorsWho owns what, and where one person holds most of the knowledge.
- DecisionsArchitectural decisions mined from commits and pull requests.
- Ask this codebaseSign inGrounded answers over the indexed code.
Maintain this repo? Claim the page
Sign in with GitHub and we check that you are an admin or maintainer of paperless-ngx/paperless-ngx. Then add a badge to the README that links readers here.
Use this repo from Claude or ChatGPT
Add this URL as a custom connector and sign in with repowise when asked. No API key to copy.
https://api.repowise.dev/mcp/paperless-ngx/paperless-ngxFor maintainers
Add a badge to your README
Every badge is public, cached, and updates on its own after every index. Nothing to install.
Repowise badge
Links to this page, with no score on it. Adding it also re-indexes the repo every week.
[](https://repowise.dev/repo/paperless-ngx/paperless-ngx?src=badge_wiki)Code health badge
The repo's health score out of 10, from the latest index.
[](https://repowise.dev/repo/paperless-ngx/paperless-ngx?src=badge_health)Code health card
A larger card with the score, its change since the last index, and when it was measured. The HTML version follows the reader's light or dark theme.
[](https://repowise.dev/repo/paperless-ngx/paperless-ngx?src=badge_card)What is paperless-ngx?
paperless-ngx is a document management system for transforming physical documents into a searchable online archive. It ingests documents, stores records with metadata and permissions, and provides browsing, search, and actions through a web interface and API. The project is primarily written in Python, with a TypeScript user interface.
Written by a model from the README and the index
Key features of paperless-ngx
- paperless-ngx transforms physical documents into a searchable online archive.
- paperless-ngx supports document ingestion through mail, scanners, and import paths.
- paperless-ngx provides browsing, search, and actions through its web interface and API.
- paperless-ngx stores documents with metadata and permissions.
- paperless-ngx supports parser discovery, plugins, and AI indexing workflows.
How paperless-ngx/paperless-ngx works
Documents enter through mail, scanners, and import paths, then backend processing transforms them into archive records. The src/documents module handles document workflows, parsing, and search-related operations. The src/paperless module coordinates shared infrastructure, including parser discovery and plugin plumbing. The src-ui directory connects the browser to backend APIs through data types, permission checks, and REST requests. The src/paperless_ai module coordinates AI-related indexing concerns, while asynchronous processing updates indexes and vector stores used to return results to the interface.
A community-supported supercharged document management system: scan, index and archive all your documents This page is a map of the paperless-ngx/paperless-ngx repository, written primarily in Python, rebuilt from the source each time it is indexed. Repowise parses every symbol, computes a dependency graph, scores per-file code health from complexity, duplication, test coverage and churn, mines git history for hotspots and ownership, and lifts the architectural decisions into documentation you can read here or query through MCP.
The codebase has 1,085 files and 8,940 symbols in 6 modules, led by TypeScript, Python and Shell. Code health is 8.1 out of 10, rated good.
Use the links above to open each view, or connect this repository to your agent for grounded answers inside Claude, Cursor, Codex or VS Code.
paperless-ngx/paperless-ngx FAQ
What is paperless-ngx?
paperless-ngx is a document management system that transforms physical documents into a searchable online archive. It provides web and API access to stored documents.
How does paperless-ngx work?
paperless-ngx ingests documents through mail, scanners, and import paths, then processes them into searchable archive records. Its web interface and API expose documents, metadata, permissions, and actions.
What language is paperless-ngx written in?
paperless-ngx is primarily written in Python. Its user interface is written in TypeScript.
How is the paperless-ngx code organized?
paperless-ngx separates backend code in src from the browser-facing interface in src-ui. The src/documents, src/paperless, and src/paperless_ai modules handle document processing, shared infrastructure, and AI-related concerns.
Who is paperless-ngx for?
paperless-ngx is for people who want to keep less paper by turning physical documents into a searchable online archive. Users interact with its web interface or API.
What license does paperless-ngx use?
paperless-ngx uses the GPL-3.0 license.
Answers written by a model from the README and the index