Update to version 2.5.0

Updates from Checkmk must always be performed from the latest patch release of the source version, to the latest patch release of the target version. An update from 2.4.0p1 to 2.5.0-2026.04.16 therefore follows this path:

2.4.0p1   2.4.0p26   2.5.0-2026.04.16

Major versions cannot be skipped. If you want to update from 2.3.0 to 2.5.0, first perform an Update to version 2.4.0.

Since 2.4.0p24, Checkmk has been using new names for its editions that better reflect their functionality. If you have installed a patch release from 2.4.0p24 onwards, you will already be familiar with the new names from the web interface. While Checkmk 2.4.0 uses the old edition abbreviation in package names, Checkmk 2.5.0 switches to the new names. For package names, this will result in the following changes:

If you have created installation scripts that use the old scheme for package names, you will need to convert these scripts to the new naming scheme.

As with any update to production software, you should check that your backups are up to date before performing the update of Checkmk.

Does this affect you? Yes.

What will you need to do? If you create your backups automatically via Setup > Maintenance > Backups, first check there that your backups are up to date and that the most recent backup jobs have completed without errors.

For more information, see the articles on Backups and on Backing up and restoring sites.

Checkmk 2.5.0 requires slightly higher system resources than 2.4.0. Before updating, it is therefore advisable to find out how much free capacity the servers used for Checkmk have available.

Does this affect you? Yes, but the extent to which you are affected depends heavily on how you use Checkmk.

What will you need to do? Make sure that there is sufficient free capacity available. For information on the expected changes in the use of hardware resources, refer to the following table:

Checkmk 2.5.0 is switching to a new metrics backend for storing and querying OpenTelemetry data.

Does this affect you? Yes, if you are already using OpenTelemetry data in monitoring with Checkmk 2.4.0.

What do you need to do? First, before updating, you need to allocate additional memory for the metrics backend. Since fewer conversions of OpenTelemetry data take place, the CPU requirements are lower than with Checkmk 2.4.0. The switch to the metrics backend means that you will need to recreate most of your configuration for OpenTelemetry monitoring. An overview is provided in Werk #19133, and the setup is explained in the article on OpenTelemetry monitoring.

In Checkmk 2.5.0, licensing is standardized for all commercial editions. For Checkmk Pro, this means that you can only perform an update if Checkmk Pro has already been licensed in Checkmk 2.4.0.

For an unlicensed Checkmk Pro, the pre-update check will fail with the following message:
Update aborted with Error: A valid and non-expired license is needed before updating

Does this affect you? This only affects users of Checkmk Pro. The other editions are not affected.

What do you need to do? In Checkmk 2.4.0, make sure that the license data has been entered and transferred to Checkmk GmbH/Inc. For instructions on how to do this, see the licensing article in the Checkmk 2.4.0 User Guide.

In Checkmk version 2.5.0, some outdated distributions are no longer supported.

Does this affect you? This will affect you if any of the following Linux distributions — still supported in 2.4.0 — is installed on your Checkmk server:

Until now, the agent plug-in for automatic agent updates was available on Linux as a binary for the x86_64 (64-bit) and i586 (32-bit) platforms. With Checkmk 2.5.0, 32-bit support is being discontinued (Werk #18925).

Does this affect you? This affects you if you use the Agent Updater and if you deliver the Agent Updater as a binary for hosts running Linux on 32-bit i586.

Starting with 2.0.0, Checkmk switched to Python 3 as the default interpreter for agent plug-ins written in Python (Werk #12149). In 2.5.0, support for Python 2 is completely removed (Werk #16908).

Does this affect you? This will affect you if you are monitoring older hosts that do not yet have a Python 3 interpreter installed.

See Werk #17685, #17686, #17687, #17688, #17689, #18111 and #18112.

Checkmk 2.5.0 uses new JavaScript features that are not available in older browsers. Which browsers are supported in which versions can be found in the System requirements.

Does this affect you? You will usually have automatic updates to the latest browser version enabled on desktop systems.

What will you need to do? Check the browser version you are using and install a more recent browser if necessary. If you are using single board computers, smart TVs or digital signage solutions to display dashboards and you have no control over the system browser, test that any required dashboards are displayed correctly before updating. If necessary, contact the hardware manufacturer for updates.

Up to Checkmk 2.2.0, every automation user could be logged in with a username and password passed via GET parameters. This option has been reduced as of Checkmk 2.3.0 and has been removed in version 2.5.0 (Werk #16223 and #17345).

Does this affect you? This change also primarily affects users who display dashboards using single board computers, smart TVs or digital signage solutions without a connected keyboard.

What will you need to do? Read the article on dashboards to learn how to enable sharing of individual dashboards in Checkmk starting with version 2.5.0.

Checkmk 2.5.0 updates Python to 3.13.9. This update affects modules installed on a Checkmk site. In many cases, post-installed modules are incompatible with Python 3.13.9. In the worst case, obsolete modules overwrite the functionality of the modules supplied by Checkmk.

Does this affect you? This will apply to you if Python modules have been installed later in your site. This may be the case, for example, if you have explicitly installed Python modules for special agents or agent-based check plug-ins that you have written yourself or obtained from the Exchange.

To find out if Python modules have been installed in your site, look for the dist-info and egg-info directories:

If the search result is not an empty list, you will need to take action.

Upgrading to Python 3.13.9 also enables stricter validation of certificate chains. Only certificate chains are accepted in which the root and intermediate certificate authorities (CAs) contain the key usage extension (Werk #19034).

Does this affect you? This only applies to you if you connect to endpoints using special agents or active checks whose server certificates use a non-compliant certificate chain. Typically, these are certificates issued using a custom CA infrastructure. Certificates from commercial CAs, from Let’s Encrypt, or created using step-ca are not affected.

You can examine suspicious certificates on the command line (OpenSSL 3 is required for this):

In this case, the certificate was not rejected. For any other issue, openssl will display the reason for the rejection.

Local files allow you to customize and extend the functionality provided by Checkmk. These files are located in the local part of the site directory structure, i.e. in ~/local and can be located in extension packages or simply 'lying around'. Local files can cause problems during an update if they no longer match the new Checkmk version.

Does this affect you? Since it is not possible for Checkmk to fully ensure the compatibility of local adaptations during an update, you should check your Checkmk site before an update to see whether local files are used, which ones they are and how they are organized.

First, use mkp list to search for extension packages (MKPs) present in the site.

Also use mkp find to get an overview of unpackaged local files in your Checkmk site.

If the output for one or both of these commands is not empty, you will need to take action.

Checkmk 2.5.0 introduces versioned successors for internal application programming interfaces (APIs) that were previously defined on an ad-hoc basis (Werk #18600). This affects cmk.inventory_ui, cmk.password_store, and cmk.server_side_programs. Since we reserve the right to make changes, the APIs mentioned use v1_unstable as their version number. We will strive not to make any incompatible changes until v1.

In addition, the directory structure of the Bakery API is being reorganized, though this rarely causes any problems.

The internal, ad-hoc defined programming interfaces will remain available, but we cannot guarantee compatibility.

Does this affect you? The topic of APIs affects you if you have extended the check plug-ins delivered with Checkmk with your own, self-written plug-ins and/or if you use plug-ins from other sources.

What do you need to do? If you encounter issues with the old, ad-hoc internal APIs, we recommend migrating the affected plug-ins to the new v1_unstable APIs. You can view the complete API documentation in any site under Help > Developer resources > Plug-in API references. You can also find the same content at docs.checkmk.com/plugin-api.

Starting with Checkmk 2.5.0, the REST API is versioned. Checkmk 2.5.0 currently includes REST API version v1.

Does this affect you? This may affect you if, for example, you use the Checkmk REST API in your own scripts.

The REST API version 1.0, which was delivered up to Checkmk 2.4.0, is compatible with the new version v1. We nevertheless recommend updating API paths in your scripts to reflect the new versioning.

Deprecated endpoints or parameters of the Checkmk REST API are marked in the API documentation with the symbol.

What do you need to do? Open the REST API documentation via Help > Developer resources > REST API. Search the page in your browser for Deprecated, check whether you are using deprecated elements in your scripts, and replace these before updating. The REST API documentation usually includes instructions on how to replace features that no longer exist in the new version.

It is possible that new major versions of the REST API will be released during the development cycle of Checkmk 2.5.0. Because Checkmk itself and the REST API are versioned separately, you have the option to decide for yourself when to migrate your scripts to a newer version of the REST API. Deprecations of REST API versions — which are announced well in advance via Werks — take effect only with the next major version of Checkmk.

As in every Checkmk version, there are also changes to the software in the current 2.5.0 version which may have repercussions on your Checkmk installation. In Checkmk these changes are organized and documented in what we refer to as our Werks. A so-called incompatible change requires that you make manual modifications in order to allow existing functions to continue to run as usual and/or to be able to use new functions.

Does this affect you? In general there will be incompatible changes that will also affect your Checkmk installation, it is however impossible to make a general statement covering all possible situations. In this article we have collected those issues that apply to all or most Checkmk installations. In any case there may be additional changes that are relevant to you, for example in checks that you use in your installation.

What will you need to do? Following every update — including patch versions — Checkmk will show you the number and content of incompatible changes and ask you to check and take note of them. Before performing the update is the right time to check for any changes from version 2.4.0 that may have an impact on the update.

Starting with Checkmk 2.3.0, such Werks are no longer carried over, because by default only the Werks from the target version are displayed in Checkmk (Werk #15292). However, since Checkmk 2.5.0, all unconfirmed, incompatible Werks from the source version are copied during the update, so that information about these Werks is not lost during the update (Werk #15365).

It is also a good idea to get an overview of the incompatible changes in version 2.5.0 before the update: Open the list of Werks on the Checkmk website. In the description of a Werk, you will find information on what you may need to do to make the change compatible.

After you have carried out the update, the number and content of the incompatible changes will be displayed in the Checkmk interface and you will be asked to check and take note of them. Links help you to check so that you can find out with just a few clicks whether you are using an affected component. If it is certain that a Werk has no impact or you have made the required changes, confirm the Werk with Acknowledge.

In this section we describe the best practices that we follow even when updating large Checkmk environments. These are certainly not mandatory in every environment, but they can make the process of updating easier for you.

There are two different procedures for performing an update of all sites included in a distributed monitoring:

In particular, if you want to update while the system is running, you should read the notes in the general article on Updates and Upgrades.

Nothing fundamental has changed with the actual update of the software in Checkmk 2.5.0, i.e. you install the new version, perform the update of the Checkmk site, rectify any possible conflicts and check and confirm the incompatible changes.

Perform the update procedure as described in the article on Updates and Upgrades.

The user interface (GUI) in Checkmk has undergone a major overhaul in 2.5.0. For example, newly-created sites now have a welcome page, the search has been redesigned, activating changes is possible without leaving the currently open page, and more assistants are available, for example to quickly add the first hosts to a monitoring. Nevertheless, you can still use the general workflows you are familiar with from the 2.4.0 version in 2.5.0 with only a moderate learning curve.

We will present these changes in this User Guide’s articles — and in the Beginner’s Guide you will find a detailed introduction, including the most important elements of the user interface.

As with every major version, Checkmk 2.5.0 introduces a whole new set of check plug-ins. If you do not use the 'discovery check', i.e. the automatic update of the service configuration via the periodic service discovery, you will have to search for services on quite a number of hosts.

If your hosts are organized accordingly (e.g. in folders), you can generally use the Bulk discovery function for this. This function can be found under Setup > Hosts > Hosts and then in the Hosts > Run bulk service discovery menu.

In some cases, check plug-ins had to be moved out, or check plug-ins had to switch to new APIs.

Does this affect you? The risk of being affected is present if you monitor hardware with a very long lifecycle, especially using special agents.

What will you need to do? If services disappear following the update, search the Werks for the manufacturer of the monitored products. In most cases, you will have to switch to new APIs or, in rare cases, use packages from the Exchange to monitor a specific hardware or software component.

Does this affect you? This will only apply to you if you have explicitly installed Python modules for special agents or agent-based check plug-ins that you have written yourself or obtained from the Exchange and have removed these in the course of preparing for the update.

Until now, the Agent Controller for Linux was only available for the x86_64 platform; in Checkmk 2.5.0, aarch64 is being added.

Does this affect you? If you have hosts in monitoring that run Linux on 64-bit ARM (aarch64), you previously had to transmit the agent output unencrypted or set up an SSH tunnel. Since Checkmk 2.5.0 makes the Agent Controller available for both x86_64 and aarch64, it is no longer necessary to treat Linux hosts differently for the two platforms.

Checkmk 2.5.0 changes the storage format for inventory trees to JSON. Converting the inventory trees may result in performance gains (Werk #18032, #18033 and #18034).

Does this affect you? This will only affect you if you work extensively with the HW/SW inventory.

Currently, the status of hosts that are accessible exclusively via IPv6 is determined using the active check check_icmp. This active check provides metrics such as round-trip times and packet loss. Starting with Checkmk 2.5.0, Checkmk Micro Core (CMC) users can also use Smart Ping for these hosts (Werk #18050), although Smart Ping does not provide any metrics.

Does this affect you? Hosts without an explicit configuration of the active check check_icmp will be automatically switched over. As a result, the active check and its metrics will be removed. If this is the desired behavior, you simply need to accept the changes to the service list.

Only if you do not want to do without the metrics of the active check for these hosts, a small manual configuration change will be necessary.

What do you need to do? Adapt the configuration of the service discovery or the active check check_icmp. You can find the description and the rules to be changed in the link Werk #18050.

See Werk #17669.

See Werk #18709.

Since 2.3.0 Checkmk already contains a new active check for HTTP connections and certificates. The Check HTTP web service can be found under Setup > Services > HTTP, TCP, Email, …​ in the Networking box. The new check is significantly better performing, more robust and easier to configure than the previous Check HTTP service. In addition, it is now possible to simultaneously monitor multiple things using a single rule, for example HTTP response codes, response times and certificate validity.

In Checkmk 2.4.0 some rarely-used options within the old check have been added to the new check to make migration easier. Furthermore, we provide a migration script that maps existing calls and resulting services 1:1. With Checkmk 2.5.0, you can no longer configure new rules for the old check. It will be completely removed later.

Once the migration has been completed, you can achieve significant performance benefits by merging multiple rules, allowing a single execution of the check to produce multiple outputs, thus reducing CPU overhead. In many cases you can also generate multiple services using a single rule in the new check.

General information on the new check can be found in the two Werks #15514 and #15515. Werk #17725 describes the migration script. A detailed blog article explains the details of the possibilities, limitations and best practices for preparing and following up the migration.

If you come across applications in which the new check cannot replace the old one, you can display the command line used in the same way as in the procedure described here. You will then have the option of calling the old check, or a system-wide installed check_http via Setup > Other services > Integrate Nagios plugins.

The term management board stands for separate plug-in cards or extended BIOS functionality (Baseboard Management Controller/BMC, Management Engine/ME, Lights Out Management/LOM) for monitoring and managing the hardware in addition to the installed operating system.

Up to Checkmk 2.4.0, management boards can be configured in two ways: As a host property or as a separate host. As the configurability as a host property is very limited, in the future this option will no longer be available.

Since Checkmk 2.4.0, Redfish monitoring is an integral part of the software (Werk #17404). We explain additional background information and possible alternatives in the Monitoring management boards blog article.