How to upgrade Umbraco to a new version

Three kinds of upgrade

• Patch (18.2.1 → 18.2.2): bug and security fixes. Low risk, so do them promptly.
• Minor (18.1 → 18.2): new features, no breaking changes. Usually straightforward.
• Major (13 → 17 LTS → 18): breaking changes. Plan, test and upgrade one major version at a time, following Umbraco's upgrade path.

Step 1: Back up everything

• The database (SQL Server backup, or a copy of the SQLite file).
• The media folder or storage container.
• Your code, committed to Git.

Always upgrade a copy of the site first, never production.

Step 2: Read the upgrade notes

Check the release notes and version-specific upgrade notes in Umbraco's documentation for every version between where you are and where you're going. Check each package you use supports the new version too. The Marketplace shows supported versions on every package.

Step 3: Update the packages

If your project uses central package management (Directory.Packages.props):

<PackageVersion Include="Umbraco.Cms" Version="18.2.2" />
<PackageVersion Include="Umbraco.Cms.DevelopmentMode.Backoffice" Version="18.2.2" />

Otherwise, from the project folder:

dotnet add package Umbraco.Cms --version 18.2.2
dotnet add package Umbraco.Cms.DevelopmentMode.Backoffice --version 18.2.2

Update your Umbraco packages (Forms, Deploy and so on) and community packages to matching versions, then build:

dotnet build

Fix any compile errors. For major versions, the upgrade notes list what changed.

Step 4: Run the database upgrade

Start the site. If the database needs upgrading, Umbraco shows an upgrade screen when you go to /umbraco. Log in and click Continue.

To upgrade automatically on start-up, which is ideal for CI/CD deployments, set:

{
  "Umbraco": {
    "CMS": {
      "Unattended": { "UpgradeUnattended": true }
    }
  }
}

Step 5: Test, then deploy

• Click through key pages, forms and member logins.
• Check the backoffice: edit, save and publish content, and open each custom dashboard or property editor.
• Look at Settings › Log Viewer for new errors.
• Deploy to production using the same steps, with a rollback plan ready.

Major upgrades from Umbraco 13 or earlier

The jump to Umbraco 14+ is the big one. The backoffice was rebuilt, so AngularJS extensions must be rewritten as web components, and some packages were replaced. From Umbraco 7 or 8 there's no in-place upgrade at all: content has to be migrated to a new site.

That's exactly what we do every day. See our Upgrade Services, or get a fixed-price quote.