Paperless-ngx 3.4.2 upgrade: bug fixes, no breaking changes
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/reportedpngx_version3.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
- 3.5.0 upgrade now