We recommend that you update your Xperience by Kentico projects regularly. Updates are released in the form of:
Check the Changelog for additional details, workarounds and instructions related to individual update versions.
In rare cases, Refreshes (only major version updates) may contain breaking changes to the codebase, typically for obsolete or infrequently-used code. Check the Breaking changes sections of the Changelog to see if your codebase or other important functionality is affected.
Update automation
While the instructions on this page can be followed and performed manually, it is also possible to automate all steps of the Xperience by Kentico update process using various types of automation tools, release management software, pipelines or scripts.
If you use an AI coding assistant that supports agent skills and plugins, the project lifecycle plugin (opens in a new tab) from KentiCopilot provides an update-xperience skill. The skill determines your current and target versions, reviews every Changelog entry in between together with the update guides they link to, and then follows the procedure described on this page. Review the resulting changes as you would with any other update.
Before updating
Start by performing the update on a local development instance of your Xperience project:
After you successfully test the update locally, you can apply the update to your Xperience application's production deployment. The following steps outline the general approach, but the exact process will depend on your deployment flow and hosting environment.
There are various ways to run the update command, depending on your deployment process and environment. For example, from a deployment pipeline, a local project with a "production" configuration that connects to the production database and file system, or if possible directly on the target environment.
For deployed applications containing built assemblies, run the following dotnet (opens in a new tab) command (replace the assembly with the name of your Xperience project's DLL):
dotnet myxperienceproject.dll --kxp-updateTo skip the database backup prompt in an automated environment, add the --skip-confirmation parameter to the update command.
To confirm that the database version matches the deployed application before you relaunch, run the --kxp-db-status command. Automated pipelines can branch on the command's JSON output instead of parsing startup logs.
Admin UI localization
If your project includes admin UI translations, review and update your localized resource files after each update. Xperience updates may modify system resource strings, which can make existing translations outdated. See How updates affect translations for possible impacts of system resource string changes, and Maintain translations across updates for a step-by-step procedure.
To update your project's Xperience code libraries and administration, update all Kentico.Xperience.* NuGet packages installed in your solution to the same target version. Depending on your project, this includes:
Check all projects in your solution, not only the main web project. Kentico.Xperience packages may be installed in separate projects, like Kentico.Xperience.Core.Tests in test projects.
Open the command line prompt and navigate to the root folder of the project you want to update.
List the currently installed packages to see which Kentico.Xperience packages the project references and which updates are available. Pass a solution file to cover all projects at once.
dotnet list package --outdated
dotnet list Acme.sln package --outdatedRun the dotnet add package (opens in a new tab) command for each installed Kentico.Xperience package.
dotnet add package Kentico.Xperience.WebApp
dotnet add package Kentico.Xperience.Admin
dotnet add package Kentico.Xperience.ImageProcessing
dotnet add package Kentico.Xperience.ManagementApiRepeat for every other project in the solution that references Kentico.Xperience packages.
# Sets the project path before the 'package' argument
dotnet add ..\Acme.Web.Tests\Acme.Web.Tests.csproj package Kentico.Xperience.Core.TestsRebuild the solution.
dotnet buildTarget update version
We strongly recommend updating to the latest available version of Xperience. However, if you wish to update to a specific version, you can select it in Visual Studio's NuGet Package Manager interface or specify it when running the dotnet add package (opens in a new tab) command.
The application will not start until the NuGet package version matches your database version. To check whether the database needs an update without starting the application, run the --kxp-db-status command. Continue by updating your project's database and files.
After updating your project's NuGet packages, update the database and file system using the .NET command-line interface (CLI). This update always targets the new version of the project's NuGet packages.
Shut down your Xperience application if it is running and receives traffic.
Open the command line prompt.
Navigate to the root folder of the project you want to update.
Run the following command:
dotnet run --no-build -- --kxp-updateCommand details
If updating a deployed application containing built assemblies, use the dotnet myxperienceproject.dll --kxp-update command instead (replace the assembly with the name of your Xperience project's DLL). For more information, see the dotnet run documentation (opens in a new tab).
When updating a full project locally, add the --no-build parameter to the dotnet run command if you have already rebuilt your project after updating the NuGet packages. This option saves time and avoids another unnecessary project build before the update. To prevent errors after building the project with a configuration other than Debug mode, set the --property:Configuration parameter to the desired value.
Add the -- syntax separator before any command parameters that you wish to pass directly to the Xperience application (--kxp-update). This prevents conflicts with general .NET CLI parameters, for example when using the --help option.
If you wish to skip the database backup prompt when running the update command (e.g., in an automated environment), add the --skip-confirmation parameter. For example:
dotnet run -- --kxp-update --skip-confirmationThe command updates the project's database and in certain cases assets or folders on the file system (using SQL scripts and API operations). The database version now matches the version of the project's Xperience NuGet packages.
The update process does not automatically start the application when finished. To verify the result, run the --kxp-db-status command – the command now reports the Ready state. After the update, you can run the application again using the dotnet run command, or another suitable approach depending on your hosting environment.
Xperience by Kentico applications deployed to the SaaS environment need to be updated manually. Use the following process:
<IncludedObjectTypes> element, check the New object types for CI/CD section of the changelog for any new object types introduced by the update.The deployment process automatically ensures that the database in the SaaS environment is up-to-date.
If you are updating a development project with Continuous Integration enabled:
dotnet run --no-build -- --kxp-ci-disable or the Xperience administration settings).<IncludedObjectTypes> element in your CI repository.config file to filter object types, check the New object types for CI/CD section of the changelog for any new object types introduced by the update. Add any new object types that you wish to include in CI.--kxp-ci-store CLI command).The following steps show an example of the update process for a local development instance using Continuous Integration (suitable for an automated script, AI workflows, etc.).
Commit all pending changes under the CI repository to your source control.
Create a backup of your Xperience database and project folder.
Shut down the Xperience application, and any other applications that connect to the same database.
Disable CI.
dotnet run --no-build -- --kxp-ci-disabledotnet run --no-build -- --kxp-updateRe-enable CI.
dotnet run --no-build -- --kxp-ci-enableSerialize all objects to the CIRepository folder.
dotnet run --no-build -- --kxp-ci-storeCommit the update changes to your source control.
If your project uses the Management MCP server, you also need to make sure that the following packages are up-to-date:
dotnet add package Kentico.Xperience.ManagementApi@kentico/management-api-mcp@latest argument in your MCP server configuration. This ensures that the latest version of the package is installed automatically when the server starts.Restart the MCP server after the update so that it loads any changes to the management API.
If you have one or more projects for custom administration development, remember to perform the following when updating to a newer Xperience by Kentico version:
Update the Xperience by Kentico NuGet packages installed in the custom admin back-end project.
Update the dependencies of your custom admin client project – @kentico/xperience-admin-base, @kentico/xperience-admin-components, @kentico/xperience-webpack-config, etc. Use the npm-update (opens in a new tab) command:
# Switches to the directory containing client module code
cd ..\Acme.Web.Admin\Client
npm updateIf you have installed the Xperience project templates package on your machine, we recommend keeping the templates up-to-date. This is required if you wish to create new projects that include released features and fixes.
To update the Xperience project templates, open the command line and run:
dotnet new update