To install Paperless-ngx on Ubuntu, first have Docker and Docker Compose ready, then either use the project’s guided installation script or configure its Docker Compose files yourself. For a manual installation, the key choices are the database template, persistent storage paths, and file permissions; after starting the stack, open its web interface to create the initial superuser. Paperless-ngx’s setup guide does not specify a minimum Ubuntu release, so check Docker’s current Ubuntu installation instructions for host-specific requirements.
Choose a guided or manual installation
| Route | What it does | Best fit |
|---|---|---|
| Guided installation script | Asks configuration questions, creates the necessary files, pulls the image, starts the containers, and creates the superuser. | A simpler setup when you are comfortable running the project’s script. |
| Manual Docker Compose | Lets you choose a Compose template and directly configure mounts, port mapping, environment settings, and other options. | More control over the installation and its configuration. |
Both approaches are documented by the Paperless-ngx setup guide. The manual procedure below is useful if you want to review and customize the Compose configuration before starting the services.
As an Amazon Associate I earn from qualifying purchases.
Prepare Ubuntu and Docker
Paperless-ngx’s manual Compose installation requires Docker and Docker Compose. Its setup documentation does not establish a minimum Ubuntu version or provide Ubuntu-specific instructions for installing Docker, so confirm the current Docker requirements and installation steps for your Ubuntu host in Docker’s official documentation before proceeding.
Download the Compose files
-
Choose a database backend. For a new installation, Paperless-ngx recommends PostgreSQL.
-
In the project’s setup guide, choose the matching Compose template from the Docker Compose directory. Save the selected
docker-compose.*.ymltemplate asdocker-compose.yml. -
Download
docker-compose.envand.envinto the same directory asdocker-compose.yml.
If you need parsing for Office documents or email files, select a template with -tika in its filename. Tika and Gotenberg are optional services for those parsing use cases, not prerequisites for a basic installation; see the configuration documentation.
Set storage paths and permissions
Choose persistent directories
Review the volume mounts in docker-compose.yml. Set the host paths for Paperless-ngx’s consume and media folders to directories that will remain available when containers are replaced and that you include in your backups. The setup guide shows how to customize these paths.
Match the container user to your host account when needed
If Paperless-ngx cannot write to the host-side consume directory, set USERMAP_UID and USERMAP_GID to the numeric user and group IDs of the host account that should own the files. Find them on Ubuntu with:
id -u
id -gThe documented defaults are 1000 for both values, but check the IDs on your host rather than assuming they match. Paperless-ngx uses these settings to change folder ownership; details are in its configuration documentation.
Change the web port only if necessary
The Compose file maps a host port to the application’s internal port 8000. You can change the host-side port—for example, the setup guide illustrates mapping host port 8010 to container port 8000—but do not change the internal port unless you have a specific reason. The URL you open later must use the host-side port from your mapping.
Review settings and start the services
Put Paperless-ngx environment settings in docker-compose.env; Docker Compose does not use paperless.conf. Review credentials and secret handling before making the service accessible beyond your machine. Paperless-ngx supports Docker secrets through settings whose names end in _FILE; see the configuration guide and setup guide for details.
From the directory containing the Compose files, pull the images and start the stack:
Rank #4
docker compose pull
docker compose up -dThe bundled Compose deployment includes a Redis-compatible message broker; Valkey is the default in the bundled files, and the project documents compatible alternatives in its configuration guide and FAQs. The setup guide says images are pulled from GitHub Container Registry by default; Docker Hub can be used instead by changing the image setting.
Open Paperless-ngx for the first time
Unless you changed the host-port mapping, open http://127.0.0.1:8000 on the Ubuntu machine. From another device, use the Ubuntu host’s address and the mapped port instead. On first access, Paperless-ngx prompts you to create a superuser. Because a superuser has full access to documents and other objects, the setup guide suggests considering a separate normal account for everyday use.
Troubleshoot common setup issues
New files in the consume folder are not detected
The default watcher may not notice new files on a filesystem without inotify support, including some NFS mounts. Configure PAPERLESS_CONSUMER_POLLING_INTERVAL to a positive value if you use such a filesystem; see the setup guide.
Best Value
Paperless-ngx cannot write to a mounted folder
Check the host directory’s ownership and permissions, then verify that USERMAP_UID and USERMAP_GID match the intended host user and group IDs. The configuration guide explains how Paperless-ngx applies those IDs to folder ownership.
Protect the installation before upgrades
Back up before upgrading or migrating, and make sure the backup can be restored. Preserve both your documents and application data. The administration guide documents an exporter for documents and metadata: Paperless-ngx administration. For an upgrade or migration, consult the current project guidance rather than treating the new-installation steps here as an upgrade procedure.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
