Upgrade your project
This is the guide for upgrading existing installations in general.
Last updated
Was this helpful?
This is the guide for upgrading existing installations in general.
Last updated
Was this helpful?
In this article, you will find everything you need to upgrade your Umbraco CMS project.
You will find instructions on how to upgrade to a new minor or major version as well as how to run upgrades unattended.
The following lists a few things to be aware of before initiating an upgrade of your Umbraco CMS project.
Sometimes there are exceptions to general upgrade guidelines. These are listed in the . Be sure to read this article before moving on.
Check if your setup meets the for the new versions you will be upgrading your project to.
Things may go wrong for different reasons. Be sure to ALWAYS keep a backup of both your site's files and the database. This way you can always return to a version that you know works.
Before upgrading to a new major version, check if the packages you're using are compatible with the version you're upgrading to. On the package's download page, in the Project compatibility area, click View details to check version-specific compatibility.
The steps outlined in this article apply to modern Umbraco from version 10 and later versions.
Are you upgrading to a minor for Umbraco 6, 7, or 8 you can find the appropriate guide below:
You can upgrade to a new major of Umbraco CMS directly by using NuGet.
Switching to a new major of Umbraco CMS also means switching to a new .NET version. You need to make sure that any packages used on your site are compatible with this version before upgrading.
The package compatibility can be checked on the package's download page. Locate the Project compatibility area and select View details to check version-specific compatibility.
Use the table below to determine which .NET version to upgrade to when going through the steps below.
15
9.0
14
8.0
13
8.0
12
7.0
11
7.0
10
6.0.5
It's recommended that you upgrade the site offline and test the upgrade fully before deploying it to the production environment.
Stop your site in IIS to prevent any changes from being made while you are upgrading.
Open your Umbraco project in Visual Studio.
Right-click on the project name in the Solution Explorer and select Properties.
Select the .NET version from the Target Framework drop-down.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
Go to the Installed tab in the NuGet Package manager.
Upgrade Umbraco.Cms.
a. Select the correct version from the Version drop-down.
b. Click Install to upgrade your project.
Make sure that your connection string has TrustServerCertificate=True in order to complete the upgrade successfully:
Restart your site in IIS, then build and run your project to finish the installation.
NuGet installs the latest version of the package when you use the dotnet add package command unless you specify a package version:
dotnet add package Umbraco.Cms --version <VERSION>
Add a package reference to your project by executing the dotnet add package Umbraco.Cms command in the directory that contains your project file.
Run dotnet restore to install the package.
For v9: If you are using SQL CE in your project you will need to run dotnet add package Umbraco.Cms.SqlCe --version <VERSION> before running the dotnet restore command. From v10, SQL CE has been replaced with SQLite so a dotnet restore should be sufficient. If this is not working then you will need to run dotnet add package Umbraco.Cms.Persistence.Sqlite --version <VERSION> and then dotnet restore.
When the command completes, open the .csproj file to make sure the package reference was updated:
When upgrading your Umbraco project, it is possible to enable the upgrade to run unattended. This means that you will not need to run through the installation wizard when upgrading.
Below you will find the steps you need to take in order to upgrade your project unattended.
Add the Umbraco:Cms:Unattended:UpgradeUnattended configuration key.
Set the value of the key to true.
With the correct configuration applied, the project will be upgraded on the next boot.
The Runtime level will use Run instead of Upgrade to allow the website to continue to boot up directly after the migration is run. This happens instead of initiating the otherwise required restart.
Follow the steps outlined below to use unattended upgrades in a load balanced setup.
Deploy to all environments.
Set the Umbraco:CMS:Unattended:UpgradeUnattended configuration key to true for the Main server only.
Boot the Main server and the upgrade will run automatically.
Wait for the upgrade to complete.
Boot the Read-Only servers and make sure they do not show the “upgrade required” screen.
It is recommended that you upgrade to the closest version before upgrading to the latest version. For Umbraco 10, the closest long-term support version is Umbraco 13. Once upgraded to Umbraco 13, you can upgrade to Umbraco 14.
If you are upgrading a Cloud project locally from version 14 to 15, remove the Umbraco.Cloud.Cms.PublicAccess and Umbraco.Cloud.Identity.Cms packages. For more details, see in the Umbraco Cloud Documentation.
If you have other packages like Umbraco Forms installed, upgrade them before upgrading Umbraco.CMS. Consult the if relevant.
In Umbraco 13, we have moved to using the .
If your database experiences timeout issues after an upgrade, it might be due to 'startupTimeLimit' configuration.
To fix the issue, try increasing the in the web.config file. Additionally, you can set the value in the in the appsettings.json file.
Check out the section about .
Upgrade Umbraco via NuGet ()