Paperless-ngx

What it does

Paperless-ngx turns paper into a searchable archive. Scan or photograph a letter, drop in a PDF or forward an email, and it reads the text, files it and suggests who it is from and what kind of document it is. Find any bill, payslip, warranty or school letter by typing a word. It runs on your own computer or server, so your private documents stay at home.

• Reads the text of every scan so you can search all your paperwork
• Learns to tag and file new documents automatically
• Imports from a scanner folder, email or phone
• Workflows, custom fields and saved views for bills and warranties

Great for: Households drowning in letters, bills and receipts who want to go paperless without a cloud service.

Make it yours: ideas

Pick an idea to start from, or describe your own.

• Settings, no code Auto-file bills by supplier and year “Set up Paperless so my energy, water, council tax and phone bills are tagged automatically and stored in folders by year.” Start with this idea
• Settings, no code Pull bills straight from my email “My bills arrive as PDF attachments in Gmail. Make Paperless collect them every day and tag them as Bills.” Start with this idea
• Settings, no code Warranties and receipts with an end date “When I scan a receipt for an appliance, let me record when the warranty ends, and show me which warranties end in the next 3 months.” Start with this idea
• Extend: themes, plugins, API Snap a letter on my phone and it's filed “I want to take a photo of a letter on my iPhone and have it land in Paperless without opening a laptop.” Start with this idea
• Extend: themes, plugins, API Reminders before bills are due “Each week, send me a message listing bills with a due date in the next 7 days.” Start with this idea
• Code changes A simple dashboard for my partner “Make a simpler home page for my husband with three big buttons: Upload, Bills to pay, and Search.” Start with this idea

How easy is it to adapt?

Tags, matching rules, workflows, mail rules and custom fields cover most household needs without code. Code changes mean a Django backend (src/) and an Angular frontend (src-ui/), plus Redis and a Celery worker for processing. Your AI always tries the gentlest step first, so your version stays easy to update.

1. 1

   Settings 5 options

   No code. Change it in the app or its config.

   • Auto-file documents, e.g. anything containing "British Gas" goes to Energy bills.
   • When a document arrives or changes, assign tags or owners, send an email or call a webhook, or run on a schedule.
   • Import attachments from an email inbox and tag them automatically.
   • Track things like amount, due date or warranty end, and show "bills due this month" on the dashboard.
   • Your own colour, name and logo.
2. 2

   Extend 2 options

   Themes, plugins, webhooks and the API. Still no fork.

   • Run your own script before or after each document is processed, e.g. to notify your phone.
   • Upload from other apps, build reports or connect a phone shortcut.
3. 3

   Code 2 options

   Your AI edits the source for anything else.

   • New screens or widgets in the Angular interface.
   • New data or API behaviour in Django. Database changes need a migration.

Can I trust it?

• GPL-3.0-only. Free to use and change. If you share your changed version with other people (give them the code or app), you must share your source code under the same licence. Using it privately for yourself or your household has no extra obligations.
• Your data: stores personal data, on your own device or server. Original and archived files in the media volume; database (SQLite by default, or PostgreSQL/MariaDB) in the data volume. Files dropped in ./consume are imported; ./export holds exports.
• Other services: Redis (message broker) (required, free (included in the compose files)); Email account (IMAP) (optional, free); Apache Tika and Gotenberg (optional, free (optional containers)); AI provider (Ollama locally, or an OpenAI-compatible API) (optional, free with local Ollama, pay-per-use for cloud providers)
• Pinned version f25fd53. Every handover uses exactly this code, which we've reviewed.
• Documents are stored without encryption. Upstream warns never to run it on an untrusted host; a home server with backups is safest.
• Don't expose it to the internet without HTTPS and a strong password; turn on two-factor authentication.
• AI features send document text to the chosen provider. Use Ollama to keep everything at home.

Did it work for people?

Tell us how it went

For your AI

The project pack has the pinned version, how to run it, and where to customise it. Your prompt links to it automatically.

https://handoff.bespokeai.software/p/paperless-ngx/f25fd53/pack.md

More for food & home

Home Assistant

Run your lights, heating and smart gadgets from one private app, with easy routines.

Food & home

Mealie

Your family's recipes, weekly meal plan and shopping list in one place.

Food & home

Grocy

Know what's in your cupboards, what's going off and what to buy next.

Food & home