Upgrading from Umbraco 13 to 17 LTS: Lessons from the Trenches

Upgrading from Umbraco 13 to 17 LTS: Lessons from the Trenches

Upgrades, upgrades, upgrades!  Upgrades are a hot topic in the Umbraco community ever since version 17 was released last November. There are a lot of great reasons to upgrade to this major version besides simply moving to the latest Long-Term Supported (LTS) version. Our team here at ProWorks has a ton of Umbraco upgrade experience and are here to help you make your upgrade a success. This article will update as we learn about new challenges and find solutions. Ready? Let's do this!

See the changelog at the bottom if you're coming back to this after a while - Updated: January 22, 2026

Why Upgrade?

Let's look at why you would upgrade to the latest v17 version:

  1. Timely Security Updates - As a LTS version, your site can stay up to date with security patches and easiest to keep up to date in the future. Umbraco 17 is supported through November 27, 2028.
  2. Better Site Performance - The rebuilt HybridCache speeds up startups especially on large sites. This means less down time after deploys to live. The latest .NET version 10 framework also improves performance which helps with your page speeds.
  3. Better Back-Office Performance - The rebuilt back-office is faster and allows for standards-based extensions and future-proofed architecture that no longer relies on Angular or other external large frameworks that could no longer be supported.
  4. Deep AI Chat Integrations - The official Umbraco MCP Server only works on version 17 and allows AI to "talk" to your specific Umbraco back-office to report on, add, or modify content.
  5. Better Automation and Integration Support - The new Management API allows for automation of everything that can be done by a content editor or developer in the back-office. This is important for deep integrations with external tools, marketing automations, and AI Agent connections.
  6. Scalable Back-office - Version 17 supports load-balancing the back-office. This allows the back-office to scale out like the front-end for performance and simplifies hosting load-balanced Umbraco websites.
  7. Read even more on the official v17 release article: Umbraco 17 LTS: Final Release

There is really a lot of truly great features available in version 17 and many more on the horizon in 18 and 19. It's a perfect time to get this upgrade done so those other upgrades are less painful later.

The sections below dive into the technical details of upgrading. If you'd rather have a conversation about what an upgrade means for your organization (timeline, budget, and business impact) we're happy to help.

Schedule a Consultation

Prepare for Your Upgrade

A good result always starts with a good plan, right?

Current Umbraco Version?

First, you should assess where your site currently is. Are you on version 13? Or something older?

  • Version 8-9: You will need to upgrade to v10, then v13, then v17 - in fact, in general it is recommended to upgrade to each LTS version on your path to the latest. There may need to be custom migrations if the site uses Grid or other unsupported editors. Content migration may be preferable is some cases. v8 has API changes that could mean major code refactoring.
  • Version 10-12: Upgrade to the latest v13, then to v17. Getting to v13 should be relatively straight-forward, but an assessment is always helpful for planning.
  • Version 13: Upgrade to the latest version of v13, currently 13.13.0.

Learn more about each version here: https://releases.umbraco.com/all-releases

(Please feel free to contact ProWorks and get our recommendations)

Using Outdated Property Editors?

If you are using any deprecated or legacy property editors, its best to update them to use the latest version in v13 before upgrading.

Property editors to migrate to in v13:

  • MediaPicker -> MediaPicker3
  • Nested Content -> Block List
  • Stacked Content -> Block List
  • Grid -> Block Grid
  • Macros -> Blocks (Or remove if unused)
  • XPath in pickers -> Plan for a change to use the new dynamic root setup

By addressing these structural elements first, the content will migrate much easier to v17.

v17 Package Support?

Do you have Umbraco Packages installed (it's likely)? Go to the Umbraco Marketplace (https://marketplace.umbraco.com/) or the package Repository and verify that each package supports v17. Many of the most used packages are ready for v17 now. Some are working on it and may have a beta version that likely works well. Some may not have any v17 support.

If you're unsure and its not clear from the repo, then asking on the Umbraco Forums (https://forum.umbraco.com/) would be a good way to see how others are dealing with this package. Is there a new version coming soon? Is there a new package that effectively replaces this one?

As always, we can help give you a recommendation to move forward on. We have been doing this a long time and would love to help! Connect with us below

Custom/Bespoke Back-Office Extensions?

If your site has custom Angular.js extensions, then those will need to be re-written in the new Typescript/Lit/Web Components extension model. For the initial upgrade you can simply disable or remove them and address them after the main upgrade is complete.

Using Smidge?

Smidge was removed in v17 and you will need to reinstall it if used by any custom code or by the site in general. It is straight-forward to re-add to your site and you can learn more on the Github repo: https://github.com/Shazwazza/Smidge.

There is also an Umbraco-specific package that you can install here: https://marketplace.umbraco.com/package/umbraco.community.smidge

TipTap or TinyMCE?

Umbraco has migrated to a new RTE component called TipTap. It will migrate all of your RTEs to this new editor by default unless you install a community package, TinyMCE.Umbraco. This package will prevent the migration and keep the TinyMCE editor installed and used as in previous versions. Read more about TinyMCE.Umbraco v17 in this post.

You will need to decide if you want to keep using TinyMCE or move to TipTap. If you have TinyMCE customizations or complex RTE setups, you may want to keep TinyMCE. The package also gives you the option of easily adding premium features like AI tools. TipTap is based on ProseMirror and is more lightweight so may be preferred in some use cases.

Use Umbraco Forms?

If you use Umbraco Forms, then you may need to migrate to the new licensing structure. It is now licensed annually instead of a one-time cost. Umbraco Forms is included with Umbraco Cloud so this is less of a concern if you are hosted on Umbraco Cloud. Your choice is to license Umbraco Forms going forward or remove it in favor of a different solution.

Review Official Documentation:

Take a look at the Version Specific Upgrades documentation guide in the Official Umbraco Documentation: Version Specific Upgrades

There may be other key breaking changes highlighted there that will be important for your site.

Also, the Upgrade Details document has information on some edge cases and older versions as well: Upgrade Details

Pre-Upgrade Process

I'll assume you have solutions for all the above issues and are ready to try out an upgrade! Great! Now, take a step to make sure you have all of this in place:

Backup Your Database / Media

Always backup your database before starting. You will miss something and may need to iterate a few times to get the migrations just right.

Also, now is a good time to get a backup of the latest media and pull it locally.

Side-by-Side Setup

Ideally, you have a v13 site for reference running locally and your future v17 site ready to upgrade. These should be using separate databases and be able to run completely side-by-side. This lets you quickly iterate with v13 changes and re-run the v17 upgrade as needed. In addition, this allows you to quickly verify that the site looks and works as expected.

If you're using Git, make sure you have each version on separate feature branches.

Verify Dev Setup

Get your development setup ready for .NET 10 and Umbraco v17:

  • Install .NET 10 SDK
  • Update Visual Studio (2022 v17.12+ or 2026)

Verify Latest v13

One last check to make sure you're on the latest Umbraco v13 release. If not, do this first.

Upgrade Time!

Let's do this.

1. Update Project Target Frameworks

This can be done directly in the .csproj files through the TargetFramework element:

    <!-- Change target framework -->
    <TargetFramework>net10.0</TargetFramework>

2. Update Nuget Packages

Update all Umbraco packages to version 17.latest:

  • Umbraco.Cms
  • Umbraco.Cms.Web.Website

If using Umbraco Cloud update these as well:

  • Umbraco.Cloud.Cms
  • Umbraco.Cloud.StorageProviders.AzureBlob
  • Umbraco.Deploy.Cloud
  • Umbraco.Deploy.Contrib

Remove these packages as they aren't needed for v17:

  • Umbraco.Cloud.Cms.PublicAccess
  • Umbraco.Cloud.Identity.Cms
  • Umbraco.Cms.Web.BackOffice

Update all other packages used including Umbraco Extensions like:

  • Umbraco.Community.Contentment
  • Umbraco.Forms
  • Any other packages used that support v17

3. Delete Build Artifacts

Delete all of the bin and obj directories in each of the projects of your solution. Umbraco has reported that Visual Studio's "Clean Solution" option is sometimes not enough.

4. Code Changes

There are a few code changes needed to get the Solution compiling.

Program.cs:
  • Remove UseInstallerEndpoints() as this is now automatically setup in v17
  • Consider comparing a fresh installed Umbraco v17 Program.cs with your current code and verify that you have the latest patterns in place. I have found other areas that were missing and easy to miss.
_ViewImports.cshtml:
  • Remove Smidge references:
@* REMOVE these lines: *@
@addTagHelper *, Smidge
@inject Smidge.SmidgeHelper SmidgeHelper
Generated Models

If you used strongly typed models and have Umbraco generate them to code files in your project/solution, then the solution likely won't compile.

You have two options:

  1. Delete all generated models from the directory in your project and set the Umbraco.Cms.ModelsBuilder.ModelsMode to "InMemoryAuto" from "SourceCodeAuto" or "SourceCodeManual". This will allow you to run the upgrade then switch it back and regenerate them after the v17 back-office is working. If you do this, you will need to install the Umbraco.Cms.DevelopmentMode.Backoffice to allow the "InMemoryAuto" mode to work in v17.
  2. Tweak the v13 generated models so they compile and regenerate them after the v17 back-office is working. This involves:

Changing IPublishedContent from:

global::Umbraco.Cms.Core.Models.PublishedContent.IPublishedContent Image { get; }

To MediaWithCrops:


global::Umbraco.Cms.Core.Models.MediaWithCrops Image { get; }

Watch for IEnumerable references as well as they need to be changed to use MediaWithCrops as well. Then fix any other build errors that you see.

Ultimately you want to run the back-office so you can regenerate them. So editing them manually is a temporary solution if you're having trouble compiling the solution.

5. Configure Razor Files for .NET v10

Verify Runtime Modes

.NET 10 deprecated runtime Razor compilation. Views are now compiled at build time by default.

Verify your .csproj has the following:

   <PropertyGroup>
      <CopyRazorGenerateFilesToPublishDirectory>true</CopyRazorGenerateFilesToPublishDirectory>
   </PropertyGroup>

I recommend compiling your Razor files to find any issues at build time instead of at runtime. Remove these lines from your .csproj:

      <RazorCompileOnBuild>false</RazorCompileOnBuild>
      <RazorCompileOnPublish>false</RazorCompileOnPublish>

More on Runtime modes from the Umbraco Documentation: https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes

If you need to restore the runtime Razor view compilation or want to use InMemoryAuto model building, then you will need to install this package:

dotnet add package Umbraco.Cms.DevelopmentMode.Backoffice

Read more in the Version Specific Guide to determine if you need this package: https://docs.umbraco.com/umbraco-cms/fundamentals/setup/upgrading/version-specific#umbraco-17

6. Optional: Disable Custom Packages

If you are planning to migrate custom back-office packages after the initial upgrade is complete, then you could simply disable any custom code and exclude it from the project.

  1. Rename folders in App_Plugins with custom extensions to have ".disabled" at the end of the folder name.
  2. Update the App_Plugins content include entry in the .csproj to exclude any folders with ".disabled" at the end:
      <Content Include="App_Plugins\**" Exclude="App_Plugins\*.disabled\**">

If you have extensions added via Razor Class Library, you may need to remove the reference or delete the .dll from the bin folder.  

7. Optional: Explicitly Set LocalTimeZone

The change to use UTC by default for System Dates may have implications for your site. Read more in the Version Specific Guide on whether you want to explicitly set a server time zone in appsettings.json.

https://docs.umbraco.com/umbraco-cms/fundamentals/setup/upgrading/version-specific#umbraco-17

{
   "Umbraco": {
      "CMS": {
         "SystemDateMigration": {
            "LocalServerTimeZone": "Eastern Standard Time"
         }
      }
   }
}

8. Licensing Changes

If you are using Umbraco Deploy or Umbraco Forms, then you will need to migrate the licensing from the file-based .lic to the configuration settings in appsettings.json

Remove .lic Files

Remove the .lic files inside of the umbraco/Licenses folder for Umbraco Deploy and Umbraco Forms.

Add Licensing Configuration

For Umbraco Cloud sites, you can add these settings to your appsettings.json file. If you have a different hosting setup, you will need to replace "UMBRACO-CLOUD" with your license key.

{
  "Umbraco": {
    "Licenses": {
      "Products": {
        "Umbraco.Forms": "UMBRACO-CLOUD",
        "Umbraco.Deploy": "UMBRACO-CLOUD"
      }
    }
  }
}

Build, Run, and Test!

Is the site rendering as expected? Does the back-office load and you are able to login? If yes, you're on your way to v17.

Now its time to perform your detailed regression testing by verifying all the packages migrated as expected, all property editors are working as expected, and you can make changes as you would expect.

Here are some items you may want to focus on to verify the upgrade:

  • The site builds without errors
  • All pages render correctly
  • Backoffice login works
  • Content editing works
  • No console errors/warnings
  • Block List editors function
  • Rich text editors function
  • Media uploads work
  • Search returns results
  • Licenses show as valid
  • Forms submit and save entries

Migrating Custom Extensions to v17

Once the back-office and site appear to be working, it's time to migrate those custom extensions to v17. That process is out of scope for this article, but here are some resources to get you started:

Final Thoughts

Upgrading to v17 is worth the effort as it is the Umbraco version to take the community into the future. AI, modern web frameworks, enterprise features, and so much more make this an upgrade to prioritize. With v13 support ending December 14th, 2026 the time to start planning an upgrade is now.

Need help with your Umbraco upgrade?

Reach out to us for an initial consultation so we can help make your upgrade a success!

Schedule a Consultation

Change Log

2026-01-22: Initial Version

Author

Jason Prothero

Jason leads the team at ProWorks Corporation, an Umbraco Platinum Partner specializing in complex Umbraco CMS builds, integrations, support, and upgrades. With 17+ years of Umbraco experience and an Umbraco MVP, he has led dozens of successful projects from versions as old as Umbraco 4 to the latest Long-Term Supported (LTS) releases. Jason is also leading the charge at ProWorks around AI and how to responsibly integrate AI into Umbraco and websites to create ROI and not simply as a novelty.

comments powered by Disqus
back to top