Getting started
Paperless NGX on Raspberry Pi makes scanning, tagging, and archiving documents easier than explaining why your garage is still full of tax records from 2003. With OCR baked in, this little setup turns a cluttered inbox into a tidy, searchable archive. You’re not paying for cloud services to hold your scanned junk — you’re the server now.
What this setup does
You scan something. Paperless NGX watches for it. OCR kicks in. Metadata gets applied. Documents get sorted into something usable. And yes, you can actually find stuff by typing a few keywords.
Why it works
The Raspberry Pi runs lean and quiet, perfect for self-hosted tools. Pair it with a good scanner and you’ve got yourself a no-nonsense digital filing cabinet that fits in your hand.
Key Takeaways
- Raspberry Pi 4 is ideal for running Paperless NGX with OCR.
- Docker simplifies setup, while SANE and OCRmyPDF handle scanning and text extraction.
- Metadata, tags, and automation make document management fast and searchable.
- Regular backups and monitoring prevent disaster and data loss.
- Secure access and local control mean you stay in charge of your documents.
Choosing the Right Raspberry Pi Hardware
Model selection matters
Raspberry Pi 4 is the sweet spot here. It’s got enough muscle to handle OCR, scanning queues, and a browser-based interface without gasping for air. Sure, you can try a Pi Zero 2 W, but you’ll be waiting around long enough to alphabetize your shoe collection.
RAM and USB speeds
At least 2GB RAM is recommended. If you plan on running PostgreSQL, Docker, and a scanner all at once — go for 4GB or 8GB. USB 3.0 is key for scanner speed, especially if you’re dealing with duplex scans or high-DPI images.
Power, storage, and cooling
Use a reliable 5V 3A USB-C power supply. Cheap adapters are a fast track to corrupting your SD card. Active cooling (small fan or heatsink case) will save your Pi from thermal throttling, especially during long OCR jobs. And please — don’t use some no-name 16GB microSD. Get a 32GB or higher, Class 10 A2 card. Or better yet, boot from SSD.
GPIO and expansion
You’re probably not using GPIO for document scanning, but hey, if you’re feeling extra, you could wire up a physical scan button. Otherwise, keep those headers clear for ventilation.
Installing and Configuring Raspberry Pi OS
Flash it right
Start with Raspberry Pi OS Lite — no desktop fluff needed. Use Raspberry Pi Imager or Balena Etcher to flash it. After flashing, drop a file named ssh into the boot partition so you can connect headlessly. If you need Wi-Fi, add wpa_supplicant.conf with your network info.
Update the basics
First boot? Run your updates:
sudo apt update && sudo apt full-upgrade -yEnable SSH, set your locale and timezone with raspi-config. Then install some basics:
sudo apt install git python3-pip curl unzipLock in a static IP
You don’t want your server floating around your network. Use dhcpcd.conf or reserve an IP in your router settings. This way, you can always find it for uploading documents or poking around the logs.
Disable bloat
Disable HDMI, Wi-Fi, or Bluetooth if you’re not using them. Less heat, fewer background services to babysit, and fewer things to break.
Setting Up the Scanner Environment
SANE makes it work
SANE (Scanner Access Now Easy) is the driver layer that lets Linux talk to your scanner. Install it like this:
sudo apt install sane-utilsCheck if your scanner is supported here.
Testing the waters
Run scanimage -L to see if your scanner shows up. If it doesn’t, make sure it’s plugged into a USB 3.0 port. Still no dice? Check dmesg logs and try adding your user to the scanner group.
Tweak and test
Once detected, run a test scan:
scanimage --format=png > test.pngAdjust DPI with --resolution 300 or --resolution 600. Use grayscale to cut file size unless you need color.
Handling buttons and auto feed
Not all scanners have Linux-friendly button support. Stick to models that work well with scanimage or gscan2pdf if you want to batch scan without constant clicks.
Permissions pain
Sometimes scanimage won’t run unless you’re root. Add your user to the right groups and make sure udev rules are in place. Or just sudo through it — we’re not running a bank here.
Installing Paperless NGX
Docker makes it easier
Unless you enjoy dependency chaos, use Docker. It bundles everything — Tesseract, PostgreSQL, Redis — and keeps things clean. Start by installing Docker and Docker Compose:
curl -sSL https://get.docker.com | sh
sudo usermod -aG docker $USERReboot after that so the user group sticks.
Grab the repo
Clone the official repo:
git clone https://github.com/paperless-ngx/paperless-ngx.git
cd paperless-ngxCopy the .env.sample to .env and adjust paths and ports if needed.
Set your volumes
Create folders for your documents:
data(for internal database and app files)media(for the scanned images and PDFs)consume(where your scanner dumps new files)
Fire it up
Once you’re set:
docker-compose up -dGive it a minute, then access it via http://<your-pi-ip>:8000. Default credentials are admin / admin.
Manual install option
You could install everything manually — PostgreSQL, Python dependencies, Redis, and the app itself — but unless you’re a masochist, stick with Docker. It’s not 2008.
Integrating OCR into the Workflow
OCR is what makes it searchable
Paperless NGX uses Tesseract through OCRmyPDF. This combo converts scanned images to PDFs with embedded, searchable text. It’s like giving your documents a brain.
Install dependencies
If you’re not using Docker, install these manually:
sudo apt install tesseract-ocr ocrmypdf ghostscriptFor Docker users, these are already included.
Languages and models
Tesseract supports tons of languages. Install more with:
sudo apt install tesseract-ocr-<langcode>Like tesseract-ocr-deu for German or tesseract-ocr-jpn for Japanese.
DPI and OCR quality
OCR hates low-resolution scans. Stick to 300 DPI or higher for text. If your OCR output is gibberish, check if your scan is too dark, skewed, or blurry.
Zones and advanced OCR settings
Paperless lets you define OCR zones — regions where it should expect text. That’s handy when dealing with forms, invoices, or receipts with fixed layouts.
Retrying failures
Failed OCR? You can reprocess manually via the web interface or CLI. Sometimes it’s just a weird font or poorly scanned page. Rescan and try again.
Automating Document Ingestion
Let the Pi do the heavy lifting
Paperless NGX doesn’t just wait around. You can set it to constantly watch a folder — like your scanner’s output — and automatically pull in new documents.
Watch directory setup
Point your scanner’s software to dump PDFs into the consume folder. Paperless NGX picks it up, runs OCR, tags it, and files it away.
Schedule with systemd or cron
If you’re not using the always-on watcher, set up a cron job to check every 10 minutes:
*/10 * * * * docker exec paperless document_consumerOr use systemd timers for more control.
Filename-based tagging
Use structured filenames like 2025-11-01_Bills_Electric.pdf. Paperless can auto-tag and sort based on patterns — no need to click through menus every time.
Batch scans and multi-page files
Most scanners can bundle pages into a single PDF. That’s easier for OCR and keeps your archive tidy. But if you do batch scan as individual files, Paperless still merges them correctly.
Error handling
If something breaks — like a corrupt file — it won’t kill the queue. Paperless logs the error and skips the bad file. You can retry or delete later.
Metadata, Tagging, and Search
The secret sauce: metadata
Every scanned file can carry metadata — title, date, tags, source, and more. Paperless NGX uses this to make your stuff easy to find later. It’s like giving your documents sticky notes that don’t fall off.
Templates save time
Set up metadata templates for common doc types. Bills, insurance, taxes — each with pre-filled tags and titles. Makes filing almost fun. Almost.
Tagging smart, not hard
Tags can be user-assigned or pulled from filenames and folder paths. Want all power bills tagged “Electricity”? Add it to the tag list and let the system learn.
Structured vs unstructured tags
Structured tags help you filter smarter — think of it like categories. Unstructured tags are catch-all labels that still improve search.
Search like a human
Full-text search works across titles, tags, and content. OCR’d text is indexed too, so typing “tooth extraction 2021” will pull up that dental bill. Handy when you can’t remember if it was March or May.
Custom filters
Use filters in the web UI to combine tag, source, and content searches. You can even save filter presets for repeat queries. No more hunting for that one-off car repair invoice.
Securing and Accessing the System
Keep it in your lane
By default, Paperless NGX runs on port 8000. That’s fine for local use, but if you’re opening it up to the internet, lock it down. You don’t want strangers rifling through your receipts.
Use a reverse proxy
Set up NGINX or Traefik to handle HTTPS. Add a free Let’s Encrypt certificate with Certbot. Redirect HTTP to HTTPS and throttle brute-force attempts while you’re at it.
Authentication options
You can use local users, or integrate with OAuth2 or SSO if you’re fancy. For most folks, just change the default admin password and enable MFA.
VPN is safer than port forwarding
Instead of exposing Paperless NGX to the whole internet, use a VPN like WireGuard or Tailscale. That way, you can access your server securely from anywhere without broadcasting it to every bot on the web.
LAN-only? Fine. But make it static.
If you’re just using it locally, set a static IP and bookmark it. That way you’re not guessing IPs every time your router gets cute with DHCP.
Keep logs and audit trails
Paperless NGX logs everything from login attempts to failed scans. Review them occasionally. Not because you’re paranoid — because you’re running a server, and it’s your responsibility.
Backup and Redundancy
You will regret skipping this
Hard drives fail. SD cards corrupt. Even cloud sync can choke. If you care about your documents, you need backups. No exceptions.
Database and media files
Back up two things: the database and the document files. Use pg_dump to export PostgreSQL and copy your media and data directories.
Example PostgreSQL backup
docker exec -t paperless-db pg_dump -U paperless > backup.sqlUse rsync or Borg
Rsync is fast and works over SSH:
rsync -a --delete /home/pi/paperless/ user@remote:/backups/paperless/Or go with Borg for deduplicated, encrypted backups.
Automate it
Schedule backups with cron or systemd. Store at least one off-site — USB drive, S3 bucket, Nextcloud — just not all on the same Pi.
Snapshots for safety
If you’re using Btrfs or ZFS, take filesystem snapshots before major upgrades. Restoring from snapshot beats rebuilding from memory.
Test your backups
Don’t assume they work. Restore to a test folder once a month. If you can’t recover from your backup, you don’t really have one.
Performance Tips and Storage Strategy
Speed matters for OCR
OCR isn’t instant, especially on a Pi. Use a model with 4GB+ RAM and run from SSD instead of SD card. The faster your I/O, the quicker your files process.
Limit concurrent jobs
Tweak the OCR worker settings so the Pi doesn’t overheat. Paperless NGX allows you to cap how many OCR tasks run at once. Default is fine, but adjust if you see slowdowns.
Compress wisely
Use PDF compression, but test quality. OCRmyPDF has options like --optimize 3 and --jpeg-quality. You don’t want a tiny file that looks like it was scanned with a potato.
File naming and storage structure
Stick with YYYY-MM-DD_Category_Title.pdf format. This helps with sorting outside of Paperless too. Use folders like inbox, processed, errors to keep things organized.
Storage tips
Use a good-quality SSD with a USB-to-SATA adapter. Avoid low-end flash drives. If using a NAS, mount it via NFS or SMB and test write speeds. Sluggish mounts will bottleneck your workflow.
Monitor space
Set up alerts or use Netdata to track free disk space. OCR and PDF processing chew up space fast. Archiving hundreds of pages of receipts? You’ll be surprised how quickly it adds up.
Monitoring and Maintenance
Don’t just set it and forget it
You’re running a server now, even if it’s no bigger than a deck of cards. Check on it once in a while. Make sure it hasn’t silently died trying to OCR a 400-page book.
Use Netdata or Glances
Both give real-time system stats — CPU, RAM, disk, temp, etc. Install Netdata for dashboards or Glances for terminal-based monitoring.
Log reviews
Check Paperless NGX logs:
docker logs paperlessLook for failed imports, OCR errors, or warning messages. The logs will tell you if a scan was unreadable or a file was skipped.
Software updates
Pull latest images every month:
docker-compose pull && docker-compose up -dDon’t forget to update Tesseract models and your scanner’s firmware (if it has any).
Reboot now and then
Linux is stable, but reboots can fix weird edge cases. Schedule one monthly or reboot after major updates just to clear the pipes.
Disk check and cleanup
Run regular checks on your storage. Delete old logs and unused temp files. If your consume folder is cluttered, it means something didn’t import — fix it.
Advanced Features and API Usage
REST API is not just for devs
Paperless NGX has a full REST API. You don’t need to be a coder to use it — curl, Postman, or simple Python scripts will get the job done. You can bulk upload, search, and tag documents programmatically.
API tokens
Generate tokens via the web UI. Use them in scripts to authenticate without exposing your username and password. Example:
curl -H "Authorization: Token your_token" http://<your-pi-ip>:8000/api/documents/Webhook support
Use webhooks to trigger external actions when documents are uploaded. Want to notify your phone, log events to a dashboard, or sync tags? You can.
Batch tools and scripts
Write bash or Python scripts to rename files, move batches into the consume folder, or backup metadata. Tie them to cron jobs and forget it.
Third-party integrations
Link Paperless NGX with Nextcloud, Syncthing, or even a home assistant platform. You can sync scanned docs across devices or trigger workflows when new bills arrive.
Custom extensions
Got dev chops? Extend the web UI, create plugins, or fork the repo and build on it. It’s open source — no one’s stopping you.
Troubleshooting Common Issues
Scanner not showing up
Double-check USB ports and power. Use lsusb to verify it’s detected. If not, try another cable or power source. Also confirm your user is in the scanner group.
OCR outputs gibberish
Low DPI or bad contrast are usual suspects. Re-scan at 300 DPI in grayscale. Still bad? Test the page with OCRmyPDF directly to isolate the issue.
Files not importing
Make sure your consume folder path matches the one in .env. Check filenames for weird characters or unsupported formats. Look in the logs for clues.
Web UI is slow
Pi’s RAM might be maxed out. Restart Docker containers or the whole system. Monitor memory usage with htop or Netdata to spot bottlenecks.
Disk errors or full storage
Free up space, check SD card health with fsck, or better yet, migrate to SSD. SD cards wear out fast under heavy I/O. If you’re out of space, OCR jobs will fail quietly.
App doesn’t start
Run docker-compose logs to see what’s broken. Missing volumes or bad database config usually top the list. Recheck .env, and don’t forget to run docker-compose pull occasionally.
Final Setup Checklist
Before you walk away, check these
Make sure the system is actually doing what it’s supposed to. Here’s a quick checklist to save you the “why isn’t this working” headaches later:
- [ ] Raspberry Pi is using a solid power supply and storage
- [ ] Static IP is set and reachable
- [ ] Scanner is detected and working with
scanimage - [ ] Paperless NGX is accessible at the correct IP and port
- [ ] Docker containers are running (
docker ps) - [ ] OCR is working and searchable text appears in PDFs
- [ ] Tags and metadata apply correctly from filenames
- [ ] Consume folder is watched and processed automatically
- [ ] Daily or weekly backups are configured
- [ ] Storage is monitored and not at 95% full
- [ ] Regular updates and reboots scheduled or performed
If you checked most of those off, you’re ready to stop living in a paper mess and actually find stuff when you need it.
FAQ
Q: Can I use a network scanner instead of USB?
A: Yes, as long as SANE supports it. AirScan and networked Brother/Epson models often work out of the box.
Q: What if my OCR results are wrong?
A: Try higher DPI, better lighting, or installing language-specific Tesseract models.
Q: Does Paperless NGX support mobile uploads?
A: Yes. Use the web interface or sync tools like Nextcloud to drop mobile scans into the consume folder.
Q: Is Docker required?
A: No, but it’s easier. Manual installs give you more control, but also more headaches.
Q: Can I move the archive to a NAS?
A: Definitely. Just mount the NAS path to your media folder in Docker or your config.
