---
title: Update Xperience by Kentico projects
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

We recommend that you update your Xperience by Kentico projects regularly. Updates are released in the form of:

- **Hotfixes** – weekly fixes of issues and reported security vulnerabilities. May include improvements that increase the system's security against potential threats.
- **Refreshes** – more extensive updates that add new features, introduce changes, and fix issues. Refreshes are planned for every month, but the release schedule may vary depending on the features included in each refresh.

Check the [Changelog](https://docs.kentico.com/changelog.md) 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.

> **Tip:** **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](https://github.com/Kentico/xperience-by-kentico-kenticopilot/tree/main/plugins/kentico-project-lifecycle) from [KentiCopilot](https://docs.kentico.com/guides/development/kenticopilot.md) provides an `update-xperience` skill. The skill determines your current and target versions, reviews every [Changelog](https://docs.kentico.com/changelog.md) 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.

## Update process overview

> **Note:** **Before updating**
>
> - Create a backup of your Xperience database, project folder and the folder where you store assets (**\~/assets** by default). In case of a failed update, use these backups to restore your environment to its original state to prevent inconsistent data.
> - When updating a development project with [Continuous Integration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-integration.md) enabled, familiarize yourself with the [Update instructions for CI](#update-development-projects-with-continuous-integration).

Start by performing the update on a local development instance of your Xperience project:

1. [Update the project's Xperience NuGet packages](#update-nuget-packages).
2. [Update the project's database and files](#update-data-and-files).

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.

1. Temporarily stop your production application (provide a suitable offline page) or prepare a staging deployment that you can later swap.
2. Deploy the [updated web project](#update-nuget-packages) to your production or staging environment.
3. Perform the [database and file update](#update-data-and-files) for your production 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](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-run#description) command (replace the assembly with the name of your Xperience project's DLL):
     ```cmd
     dotnet myxperienceproject.dll --kxp-update
     ```
   - To skip the database backup prompt in an automated environment, add the `--skip-confirmation` parameter to the update command.
4. Finalize the update (relaunch the stopped production application, swap your staging and production slots, etc.).
5. If you use the [Xperience project templates package](https://docs.kentico.com/documentation/developers-and-admins/installation.md#install-project-templates-package), update your installed templates. See [Update project templates](#update-project-templates).

> **Note:** **Admin UI localization**
>
> If your project includes [admin UI translations](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md), 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](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#how-updates-affect-translations) for possible impacts of system resource string changes, and [Maintain translations across updates](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#maintain-translations-across-updates) for a step-by-step procedure.

### Update NuGet packages

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:

- **Kentico.Xperience.WebApp**
- **Kentico.Xperience.Admin**
- All installed [extension packages](https://docs.kentico.com/documentation/developers-and-admins/development/website-development-basics/configure-new-projects/xperience-by-kentico-nuget-packages.md) (for example, _Kentico.Xperience.ManagementApi_)

> **Note:** 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.

**Visual Studio**

1. Open your application in **Visual Studio**.
2. Right-click your website project in the **Solution Explorer** and select **Manage NuGet Packages**.
3. On the **Updates** card, select all **Kentico.Xperience** NuGet packages and click **Update**.
4. Repeat for every other project in the solution that references _Kentico.Xperience_ packages.
5. Rebuild the solution.

**.NET CLI**

1. Open the command line prompt and navigate to the root folder of the project you want to update.
2. 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.

   ```cmd title=".NET CLI"
   dotnet list package --outdated
   dotnet list Acme.sln package --outdated
   ```
3. Run the [dotnet add package](https://learn.microsoft.com/en-us/nuget/consume-packages/install-use-packages-dotnet-cli#install-or-update-a-package) command for each installed _Kentico.Xperience_ package.

   ```cmd title=".NET CLI"
   dotnet add package Kentico.Xperience.WebApp
   dotnet add package Kentico.Xperience.Admin
   dotnet add package Kentico.Xperience.ImageProcessing
   dotnet add package Kentico.Xperience.ManagementApi
   ```
4. Repeat for every other project in the solution that references _Kentico.Xperience_ packages.

   ```cmd title=".NET CLI"
   # Sets the project path before the 'package' argument
   dotnet add ..\Acme.Web.Tests\Acme.Web.Tests.csproj package Kentico.Xperience.Core.Tests
   ```
5. Rebuild the solution.

   ```cmd title=".NET CLI"
   dotnet build
   ```

> **Info:** **Target 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](https://learn.microsoft.com/en-us/nuget/consume-packages/install-use-packages-dotnet-cli#install-or-update-a-package) command.

The application will not start until the NuGet package version matches your database version. Continue by [updating your project's database and files](#update-data-and-files).

### Update data and files

After [updating your project's NuGet packages](#update-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.

1. Shut down your Xperience application if it is running and receives traffic.
2. Open the command line prompt.
3. Navigate to the root folder of the project you want to update.
4. Run the following command:

   ```cmd
   dotnet run --no-build -- --kxp-update
   ```

   > **Info:** **Command 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](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-run#description).
   >
   > 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](#update-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:
   >
   > ```cmd noheader
   > dotnet run -- --kxp-update --skip-confirmation
   > ```

The 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. After the update, you can run the application again using the `dotnet run` command, or another suitable approach depending on your hosting environment.

## Update projects in the SaaS environment

Xperience by Kentico applications [deployed to the SaaS environment](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md) need to be updated manually. Use the following process:

1. Update your project in a local development environment to the desired version.
   - See [Update NuGet packages](#update-nuget-packages) and [Update data and files](#update-data-and-files).
2. Create a new [deployment package](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#deploy-with-a-deployment-package).
   - Update the **$CDRepository/repository.config** file according to your [Continuous Deployment](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md) object filtering requirements. If you use the `<IncludedObjectTypes>` element, check the _New object types for CI/CD_ section of the [changelog](https://docs.kentico.com/changelog.md) for any new object types introduced by the update.
3. Redeploy the package to your Xperience Portal project.

The deployment process automatically ensures that the database in the SaaS environment is up-to-date.

## Update development projects with Continuous Integration

If you are updating a development project with [Continuous Integration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-integration.md) enabled:

- Before running the update, disable CI (via `dotnet run --no-build -- --kxp-ci-disable` or the Xperience administration settings).
- Apply the update separately for each instance in your development environment. You cannot fully synchronize the database update using your source control system and CI.
- If you use the `<IncludedObjectTypes>` element in your CI _repository.config_ file to [filter object types](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/configure-ci-cd-repositories.md), check the _New object types for CI/CD_ section of the [changelog](https://docs.kentico.com/changelog.md) for any new object types introduced by the update. Add any new object types that you wish to include in CI.
- After updating, every developer needs to **run complete serialization for all objects** to recreate the content of the _CIRepository_ folder on their instance (use the `--kxp-ci-store` CLI command).
- After one developer commits the update changes to the source control, other developers CANNOT commit or load changes until they apply the update to their own instance.

### Example – Update process with CI

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.).

1. Commit all pending changes under the CI repository to your source control.
2. Create a backup of your Xperience database and project folder.
3. Shut down the Xperience application, and any other applications that connect to the same database.
4. Disable CI.

   ```cmd title=".NET CLI"
   dotnet run --no-build -- --kxp-ci-disable
   ```
5. [Update the project's NuGet packages](#update-nuget-packages).
6. [Update project data](#update-data-and-files).

   ```cmd title=".NET CLI"
   dotnet run --no-build -- --kxp-update
   ```
7. Re-enable CI.

   ```cmd title=".NET CLI"
   dotnet run --no-build -- --kxp-ci-enable
   ```
8. Serialize all objects to the _CIRepository_ folder.

   ```cmd title=".NET CLI"
   dotnet run --no-build -- --kxp-ci-store
   ```
9. Commit the update changes to your source control.

## Update the Management MCP

If your project uses the [Management MCP server](https://docs.kentico.com/documentation/developers-and-admins/api/management-api.md), you also need to make sure that the following packages are up-to-date:

- [Kentico.Xperience.ManagementApi](https://www.nuget.org/packages/Kentico.Xperience.ManagementApi) NuGet package
  - [Update](#update-nuget-packages) this package together with your other Xperience packages.
  ```cmd title=".NET CLI"
  dotnet add package Kentico.Xperience.ManagementApi
  ```
- [@kentico/management-api-mcp](https://www.npmjs.com/package/@kentico/management-api-mcp) npm package
  - We recommend using the `@kentico/management-api-mcp@latest` argument in your [MCP server configuration](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md#add-the-mcp-server). This ensures that the latest version of the package is installed automatically when the server starts.
  - You do not need to match the npm package version to your project's Xperience NuGet packages. The MCP server reads the management API schema from your running project, so the latest version also works with older Xperience versions.

Restart the MCP server after the update so that it loads any changes to the management API.

## Update admin customization projects

If you have one or more [projects for custom administration development](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/prepare-your-environment-for-admin-development.md), 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](https://docs.npmjs.com/cli/v9/commands/npm-update) command:

  ```cmd
  # Switches to the directory containing client module code
  cd ..\Acme.Web.Admin\Client
  npm update
  ```

## Update project templates

If you have installed the [Xperience project templates package](https://docs.kentico.com/documentation/developers-and-admins/installation.md#install-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:

```cmd title="Update project templates"
dotnet new update
```