Paperless-ngx Setup on Ubuntu: Choose a Route

To set up Paperless-ngx on Ubuntu, you choose between a Docker Compose stack (recommended for most users) or a bare-metal installation using Python and a database. This guide walks you through both routes, explains the trade-offs, and gives you the exact steps to get a working document management system.

What Is Paperless-ngx?

Paperless-ngx is a free, open-source document management system that scans, indexes, and archives your paper documents. It runs on your own server, extracts text from PDFs, images, and scanned files using OCR (optical character recognition), and makes everything searchable through a web interface. You can tag documents, assign correspondents, and set up automatic filing rules. It is a community-maintained fork of the original Paperless project, which was abandoned in 2020.

Why the Setup Route Matters

Paperless-ngx has two primary ways to run on Ubuntu: Docker Compose and a native installation. Docker Compose bundles the application, its database (PostgreSQL), the search engine (Apache Tika or the built-in search), and a Redis cache into isolated containers. A native install puts Paperless-ngx directly on your Ubuntu system, using system Python, a PostgreSQL database, and systemd services. The choice affects upgrade ease, resource usage, and how much you need to know about Linux administration.

Route 1: Docker Compose (Recommended for Most)

Docker Compose is the officially recommended method because it simplifies updates and dependencies. You need Ubuntu 20.04 or newer, Docker Engine, and the Docker Compose plugin. Here is how to get started:

Install Docker Engine and the compose plugin from the official Docker repository (not the Ubuntu universe package, which can be outdated).
Create a directory for Paperless, e.g., ~/paperless-ngx.
Download the docker-compose.yml file from the Paperless-ngx GitHub repository (the file is named docker-compose.yml in the root of the repo).
Edit the docker-compose.yml to set your PAPERLESS_SECRET_KEY (a long random string) and change the default admin password if you want.
Run docker compose up -d to start the stack.
Access the web UI at http://localhost:8000 and log in with the default admin credentials (admin/admin) – you should change these immediately.

The compose file includes services for the database, Redis, the webserver, and a Tika/OCR container. It also mounts a media folder for your documents and a consume folder where you drop files to be imported.

Route 2: Bare-Metal Installation

If you prefer not to use Docker, or you are running on a very small VPS, you can install Paperless-ngx directly. This route gives you more control but requires you to manage Python, PostgreSQL, and systemd yourself. The official documentation provides a full installation script for Ubuntu/Debian. The script installs dependencies, sets up a virtual environment, configures PostgreSQL, and creates systemd services. After running it, you edit /etc/paperless.conf to set the secret key and database credentials, then run python3 manage.py migrate and create a superuser. The web UI runs on port 8000 by default.

Bare-metal is more fragile: when you upgrade Ubuntu or Python, you may need to rebuild the virtual environment. Docker isolates you from that. Unless you have a strong reason to avoid Docker, the container route is less headache.

How to Choose Between Them

Consider these factors when deciding:

Ease of upgrades: Docker Compose makes updates a matter of pulling new images and running docker compose pull and docker compose up -d. Bare-metal updates require manual steps.
Resource usage: Docker adds overhead for the container runtime, but on a typical server with 2GB RAM it is negligible. Bare-metal uses slightly less memory.
System integration: If you want Paperless to use your existing PostgreSQL instance or a custom OCR setup, bare-metal gives you more flexibility.
Your comfort level: If you are new to Linux, Docker Compose hides most of the complexity. If you are a sysadmin, bare-metal feels more transparent.

For a home user or small office, Docker Compose is the clear winner. For a production environment with custom requirements, bare-metal might be worth the extra work.

Common Problems and Fixes

Many setup issues stem from a few recurring pitfalls:

Permission errors on the consume folder: The Docker container runs as a specific user (UID 1000 by default). Ensure your host folder is writable by that user, or set PAPERLESS_CONSUME_UID and PAPERLESS_CONSUME_GID in the environment.
OCR not working: Paperless uses Tika or the built-in OCRmyPDF. If you see “OCR is not available” in the UI, check that the Tika container is running and that you have the correct PAPERLESS_TIKA_ENABLED setting.
Database connection refused: In Docker, the database hostname is the service name (e.g., db), not localhost. In bare-metal, use localhost.
Port 8000 already in use: Change the host port in the compose file or the PAPERLESS_PORT variable.
Upgrade breaks: Always back up the media folder and the database before upgrading. The official docs recommend using pg_dump for PostgreSQL.

Costs and Maintenance

Paperless-ngx itself is free. You pay for the server (or use an old PC) and electricity. Storage is the main cost: a typical scanned page as a PDF is about 50–200 KB, so 10,000 pages might take 1–2 GB. You can use any S3-compatible storage for the media folder, but the simplest is a local disk. Regular maintenance includes updating the container images (or the system packages) and checking that OCR still works after system upgrades. Backups are essential – the documents are irreplaceable. You can automate backups with a cron job that dumps the database and copies the media folder.

Frequently Asked Questions

Do I need a separate OCR tool?

No. Paperless-ngx includes OCRmyPDF (or Tika) in the Docker image, so it works out of the box. For bare-metal, the installation script installs OCRmyPDF. You only need to configure Tika if you want to extract text from images or use the built-in file classification.

Can I run Paperless-ngx on a Raspberry Pi?

Yes, but it will be slow for OCR. The Docker images support ARM64, and you can run the stack on a Pi 4 with 4GB RAM. Expect a few seconds per page for OCR. A Pi is fine for a personal archive, not for heavy scanning.

How do I import existing PDFs?

Drop them into the consume folder. Paperless detects new files, OCRs them, and adds them to the index. You can also use the web UI to upload files directly.

Is my data safe?

Yes, if you back up. Paperless stores files in the media folder and metadata in the database. If you lose either, you lose the documents. Use a backup script that copies both. No data leaves your server unless you configure remote storage.

Can I access Paperless from outside my home network?

Yes, but you should secure it. Use a reverse proxy like Nginx with HTTPS, or a VPN. Do not expose the default port 8000 directly to the internet without a firewall and strong passwords.

What is the difference between Paperless and Paperless-ngx?

Paperless-ngx is the actively maintained fork of the original Paperless. It adds a modern web UI, better OCR, and more features. The original project is no longer updated, so you should use ngx.

Final Thoughts

Both routes work. If you want the least friction, Docker Compose. If you want to avoid Docker, the bare-metal script is reliable. Whichever you choose, set up a backup from day one. Paperless-ngx is a powerful tool that can turn a pile of paper into a searchable digital archive, and on Ubuntu it is surprisingly easy to get running.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →