How to prepare for a Pimcore upgrade: Key risks, stages, and best practices

In this article, you will learn:

• when it is worth planning a Pimcore upgrade,
• what benefits upgrading the platform can deliver,
• which risks should be considered before starting the project,
• what the migration process looks like step by step,
• how to choose the right upgrade approach,
• how to prepare your organisation for a safe and successful upgrade.

When does your Pimcore system need an upgrade?

Not every update needs to be implemented immediately. However, there are situations where postponing an upgrade increases technical risk, makes future development more difficult, and raises long-term maintenance costs.

It is worth planning an upgrade if:

• support for your current version has officially ended,
• your system relies on outdated libraries or an unsupported PHP version,
• implementing new features is becoming increasingly difficult,
• compatibility issues with extensions are starting to appear,
• documentation and technical support are becoming harder to find,
• your organization is planning to expand the platform or introduce new integrations,
• technical debt continues to grow.

Three reasons to upgrade your Pimcore system to version X

If you're running Pimcore version 5, upgrading is a must. This edition is not supported anymore. Security updates to fix newly discovered vulnerabilities are no longer being prepared for Pimcore editions 5 and 6. If you’re using this version of the software, you can upgrade to a paid LTS (Long-Term Support) version. Note, however, that this requires a paid subscription.

Below are the most important arguments in favour of upgrading to Pimcore X.

1. Outdated software is a huge security risk.

If your system version uses outdated libraries and extensions, a simple error is just a tiny issue. It could mean security vulnerabilities. This is the case, for example, in the aforementioned version 5, for which updates were discontinued on 9.12.2019, and version 6, for which they were discontinued on 23.06.2021.

If you are using an older release of the system, you also have to consider that it may be running a version of PHP without security updates. The latest version of the software is usually the safest.

2. By holding off on upgrading, you are increasing your technical debt.

This can mean a situation where you take the seemingly cheaper option of not investing in upgrading your system, but eventually, it actually requires you to spend much more money. Removing the accumulated tech debt that permeates the entire application will be pricier than countering it on an ongoing basis. You may find that the time spent on updating to the latest version could have been spent on an upgrade.

From the perspective of the team employed in a company, programmers are usually more willing to apply to organizations implementing projects that they find attractively challenging. They look more favourably on technological novelties than on legacy code. Lack of technical documentation for outdated software versions or upgrade paths is also an additional reason to upgrade. Working with not supported software is nothing but a pain for them. If you somehow manage to convince them to work with old Pimcore, it won't be cheap.

The sooner you perform a Pimcore upgrade, the lower the costs and the less work required to perform it. Otherwise, you have to deal with a decrease in software performance and an increased risk of errors. And developers quitting.

3. If you decide to stay with the old version of the Pimcore, you are blocking new possibilities.

You won't be able to take advantage of feature updates or brand-new developments from Pimcore, for instance because you’ll be unable to install new features. This means that even though you originally opted for a flexible and powerful solution, by sticking with an older version, you are locking yourself into a limited (and, as we've already mentioned, increasingly insecure) default feature set. It's possible to manage it manually until some point... but what for? Again, of course, it will cost you more than an update.

You already know why it's worth upgrading your Pimcore system. There are, of course, challenges involved. But you can prepare for them, manage them in advance and, as a result, avoid potential risks.

What risks should I anticipate when upgrading?

• You should be aware that a migration that involves going through several versions is more difficult than through just a single version. For example, moving from Pimcore 5 to 6, then from Pimcore 6 to Pimcore X. Here, a lot also depends on the migration variant (3 possible variants are described below).
• The difficulty of the upgrade will be proportional to the complexity of the project. The more extensions, customized code, special system settings, and - what's most important - the tech debt, the more work, and risk are involved.
• If the project does not have documentation and automated testing, it’s possible for features to regress unnoticed. You may need to start with default values.
• When migrating, there can be a loss of database integrity. Data objects may not be merged anymore. This is a huge business risk, especially considering the purpose of Pimcore implementation in your business. However, if backups are maintained and robust testing is carried out, this risk is minimized.
• There may also be issues arising from changes to Pimcore itself.

Firstly, the Pimcore extensions you have may no longer be updated. In this case, we have 3 choices: we try to update these extensions yourself, give up on them, or postpone the upgrade until the authors of the extensions release an update.

Secondly, the code written for the previous versions of Pimcore may become obsolete due to the upgrade. In such a situation, refactoring (i.e. restructuring the existing code) is needed.

It’s also worth considering that the upgrade path provided by Pimcore is not perfect, and you’ll have to fine-tune the upgrade yourself. Here again, our specialists can help you.

From our experience

„Every Pimcore upgrade should be seen as part of the platform’s long-term development rather than simply a software update. Keeping the platform up to date makes it easier to evolve the system, reduces technical debt, and enables organizations to take advantage of new features and integrations in a secure and controlled way.” - Maciej Pałubicki, CEO, Tandemite

A good example is the project delivered for ZARYS International Group. The company's B2B platform, built on Shopware and integrated with Pimcore PIM, SAP, and Microsoft Azure, was designed with future growth and scalability in mind. In environments like this, regular platform upgrades help maintain compatibility with connected systems, provide access to new functionality, and support the continued development of integrations and business processes.

How does the migration process work?

The details depend on which upgrade option you opt for (the three possible ones are described further on). However, as a rule, the basic steps are:

1. Downtime, which means shutting down the production server. This is done so that no data from new user activities is lost.
2. Coordination of the upgrade with infrastructure administrators, e.g.: switching PHP versions, monitoring server resources and creating a database backup.
3. Creating backup copies of data and files (called assets).
4. Optionally: running a parallel infrastructure with different software versions, e.g. different versions of PHP and Elasticsearch (a dual infrastructure gives you the possibility to revert to the previous version if the upgrade fails).
5. Process verification, testing, and patches.
6. In case of failure: restore the old version from the database backup.

Pimcore X upgrade options

Upgrading to Pimcore X can be done in three ways. Below, we describe the advantages and disadvantages of each of them.

The choice of upgrade approach depends primarily on the system architecture and the organization’s business objectives. A technical assessment carried out before the project begins helps identify the most suitable scenario, reduce risk, and ensure the upgrade runs as smoothly as possible.

Instead of a conclusion: how to prepare your organization for a Pimcore upgrade

A successful Pimcore upgrade requires both technical and business preparation. Before the project begins, it is important to define responsibilities, prepare the environment, and involve the people who will validate the system after the upgrade.

Preparation should cover the following areas:

• Assign a business owner
  Appoint a single person to coordinate decisions on the business side, set priorities, and act as the main point of contact for the upgrade team.
• Audit the current version and integrations
  Review the current Pimcore version, installed extensions, custom developments, and integrations with ERP, CRM, e-commerce platforms, and other business applications.
• Create backups
  Back up the database, files, and digital assets so the previous version can be safely restored if any issues arise during the upgrade.
• Set up a staging environment
  A staging environment that closely mirrors production allows the upgrade, testing, and fixes to be carried out without affecting day-to-day business operations.
• Plan user acceptance testing (UAT)
  The testing process should involve the people who use Pimcore every day, such as content managers, product data administrators, and sales and marketing teams.
• Coordinate with infrastructure administrators
  The upgrade may require changes to the PHP version, server configuration, Elasticsearch, or other infrastructure components.
• Verify integrations
  After the upgrade, verify that data flows correctly between Pimcore and connected systems, particularly ERP, e-commerce platforms, marketplaces, CRM, and marketing tools.
• Plan communication and downtime
  Users and business teams should know in advance when the upgrade will take place, how long the expected downtime will be, and which activities should be avoided during the maintenance window.
• Allocate a budget for adjustments and refactoring
  The scope of work depends on the age of the system, the number of versions being skipped, and the level of customization. It is worth setting aside a contingency budget for code changes, extensions, and integrations.

Careful preparation shortens the overall project timeline, simplifies testing, and significantly reduces the risk of downtime and post-upgrade issues.