Upgrading from PSPDFKit Server

PSPDFKit Server no longer receives updates as of version 2024.1.2 and has been replaced by PSPDFKit Document Engine. This guide will walk you through the necessary steps to migrate your existing Server instance to Document Engine.

Before the Upgrade

Ensure you’re running the latest version of Server (2024.1.2) before migrating to Document Engine. To upgrade, follow PSPDFKit Server’s migration guides.

If you haven’t done so yet, now is a good time to carefully read our overview of the upgrade process.

Updating the Docker Image

To upgrade to Document Engine, you’ll need to change Server’s Docker image from pspdfkit/pspdfkit to pspdfkit/document-engine.

Use the following image for the Document Engine version 1.3.0:


We publish our images to DockerHub and AWS ECR. Refer to our Docker registries guide to learn more.


Always use a specific image version tag; never rely on :latest.

License Changes

Document Engine uses a new license format that streamlines licensing. Refer to our licensing guide to learn more about Document Engine licensing.

No migration is necessary for your license at this point. Existing Server licenses will continue to work just like before, and you can continue using them with Document Engine without any problems.

Once your license is migrated, you’ll receive additional information about the license update.

We plan to drop support for legacy licenses in Document Engine builds produced after 15 May 2024.

Configuration Changes

No migration is necessary. Your existing configuration options will continue working in Document Engine without any changes.

API Changes

No migration is necessary. The Document Engine API is 100 percent compatible with the PSPDFKit Server API.


The metrics tag family will change from pspdfkit-server to pspdfkit-document-engine. If you’re using metrics, make sure to update your queries to reflect the new value.

Changes to Web Server-Backed

There are important changes to PSPDFKit for Web integration with Document Engine that you should be aware of.

No Matching Versions with PSPDFKit for Web

PSPDFKit Server and PSPDFKit for Web historically required matching versions to work together. This requirement has been dropped in PSPDFKit Server (and PSPDFKit for Web) version 2024.1.0.

With the introduction of Document Engine, we’re extending this concept even further: Document Engine will no longer require a matching version of PSPDFKit for Web. Both products will have separate release cycles and versions.

Document Engine maintains a minimal version of PSPDFKit for Web that’s fully supported. If the version requirement isn’t met, Document Engine will refuse to connect to the PSPDFKit for Web client.


This allows you to update the Document Engine to a newer version without influencing your frontend, as was necessary with PSPDFKit Server.

Document Engine also maintains a maximum recommended version of PSPDFKit for Web that’s known to be fully working with a particular Document Engine version. This version is used for the version of PSPDFKit for Web integrated in the documents view in the Document Engine dashboard and served as <document_engine_url>/pspdfkit.js.

PSPDFKit for Web maintains a minimal version of Document Engine that’s required to fully support its features. If the version requirement isn’t met, PSPDFKit for Web will refuse to connect to Document Engine.


To streamline the support process, always specify both PSPDFKit for Web and Document Engine versions in your support requests.

Serving PSPDFKit for Web

PSPDFKit Server historically shipped with a matching version of the Web SDK. This is no longer true since 2024.1.0.

Some of our customers reported problems with this change. We listened and are now providing a CDN with the Web SDK bundles that can be used to simplify the setup.

Refer to our guide on integrating the Web SDK with Document Engine for more details.