Paperless-ngx 3.4.2 upgrade: bug fixes, no breaking changes

released
lab run
upgraded from
3.4.1
guest
Ubuntu 26.04 VM
tested
yes, in our lab

Summary

Paperless-ngx 3.4.2 is a small maintenance release. It has 11 bug fixes, 14 dependency bumps and no new features. Most fixes are in the web UI, mostly on mobile. There are also updates to Django and related Python packages.

Breaking changes and deprecations

The release notes list none, and we saw none in our test. This is what the notes say, not something we checked in the code.

Tested in our lab

We installed 3.4.1 with the project’s Docker Compose (SQLite) files, added data, then upgraded to 3.4.2.

  • 3.4.1 came up healthy. We uploaded one text document and created one tag.
  • We stopped the stack with docker compose down, changed the image tag to 3.4.2, pulled it and started it again.
  • 3.4.2 became healthy, and /api/status/ reported pngx_version 3.4.2.
  • The document and tag from before the upgrade were still there, and the search index status was OK. A search for “ACME” found the old document.
  • No database migrations were left unapplied.
  • A new document uploaded after the upgrade was consumed normally.
  • Searching the container logs for “error”, “traceback” and “critical” found only a task name (paperless_mail.mail.error_callback) in the startup task list.

What we did not test: the web UI itself (including the mobile fixes), PostgreSQL setups, OCR of scanned PDFs, mail fetching, or the Celery import fix (#14653). We only used the API with plain-text uploads.

One note for new installs: the compose env file ships with PAPERLESS_SECRET_KEY=change-me, and the container refuses to start until you set a real value. This is not new to 3.4.2. We hit it on 3.4.1, where the container exited with “PAPERLESS_SECRET_KEY is not set or is the default ‘change-me’ value”. Set your own key first.

Lab log

$ docker compose up -d
 Container pl-webserver-1 Started
$ docker compose ps
pl-webserver-1   ghcr.io/paperless-ngx/paperless-ngx:3.4.1   "/init"   webserver   About a minute ago   Up About a minute (healthy)   0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp
$ curl -s -u admin:[redacted] http://localhost:8000/api/status/
{"pngx_version":"3.4.1",[...]
$ docker compose down
 Network pl_default Removed
$ sed -i "s#paperless-ngx:3.4.1#paperless-ngx:3.4.2#" docker-compose.yml
$ docker compose pull
 Image ghcr.io/paperless-ngx/paperless-ngx:3.4.2 Pulled
$ docker compose up -d
 Container pl-webserver-1 Started
$ docker compose ps
pl-webserver-1   ghcr.io/paperless-ngx/paperless-ngx:3.4.2   "/init"   webserver   About a minute ago   Up About a minute (healthy)   0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp
$ curl -s -u admin:[redacted] http://localhost:8000/api/status/
{"pngx_version":"3.4.2",[...]
$ curl -s -u admin:[redacted] "http://localhost:8000/api/documents/?fields=id,title"
{"count":2,"next":null,"previous":null,"results":[{"id":2,"title":"Post-upgrade"},{"id":1,"title":"Lab invoice"}]}
$ curl -s -u admin:[redacted] http://localhost:8000/api/status/ | grep -o "\"unapplied_migrations\":[^]]*]"
"unapplied_migrations":[]

Reported by others

Nothing beyond the official release notes. They mention a fix so the index and LLM index start-up waits for Tesseract language packs to install (#14670), and a filelock bump for ACL-related fixes (#14656). We did not test either.

Verdict

Upgrade now if you run 3.4.1 or earlier in Docker. Take your usual backup first (for example with document_exporter). The upgrade was uneventful in our test, though it covered only basic API use and not the UI.

sources

other Paperless-ngx releases