Upgrading Umbraco versions

Some helpful notes

While most of this post relates to upgrades that have been performed from version 4.7.2 > 6.1.6* the same procedures and principles apply to other version upgrades although​ specific files may vary.

*At the time of writing this v6.1.6 was the latest stable release

UPDATE (1st May 2014)

With the release of Umbraco 6.2 there is a new membership API built in. While Umbraco has said that the legacy Membership providers are still there I have had issues with legacy code running in v6.2.
To be safe and avoid any issues with sites using membership I suggest only upgrading to v6.1.6 at the most.
Of course if you have the time to possibly rewrite some of your code in the event of something breaking then feel free :)

A few important things to keep in mind

  • Backup: ​I mean it. Backup the database and backup all of the site files. The best approach is to actually setup an entirely new copy of the site for upgrade. Also backup between upgrades, if you get from version 4.7.2 to version 4.11.10 and it works without any bugs then back it up before performing the next leap. There is nothing worse than having to go right back to square one because something went wrong with the next version upgrade so back it all up to be safe.

  • Installed packages: Are the packages currently installed compatible with the newer version of Umbraco you are aiming to upgrade to? If not are there updates for them? (Especially you should upgrade uComponents. Version 6.0.0 of uComponents works best with Umbraco 6.1.x and you can simply do an install from the Umbraco back office of the new version to update it.)
  • Umbraco upgrades can drop support for various things: Be prepared to have to fix things during / after upgrading as sometimes things may no longer work.

  • Don't just blindly overwrite files: If there has been customisation done to the Umbraco instance you are working on then these will get lost. Investigate and plan what you can overwrite and what you will have to merge.

  • Visual Studio can cause you headaches: ​When overwriting and merging files don't do this with the solution open in Visual Studio. Also don't assume that the references in the solution will be updated with the dll file versions! compare the file versions or even better remove and then re-add any references that have updated dlls. 

  • Don't run the Install step in Chrome: With Chrome's heaving caching I have seen errors thrown when there isn't anything wrong with the Install process. This can lead to looking for a "ghost in the machine". Save yourself some trouble and don't run the installer in Chrome.

  • Refresh the Umbraco cache: Once everything is upgraded make sure you republish the site to ensure the cache is updated. Under 'Developer' there is a new 'Examine management' tool, you should use this to rebuild the 'Indexers' and 'Searchers' indexes as well as optimize them. ​Also under 'Developer' there is a new 'log manager'​ take the time to clear out any old logs as they take up a fair bit of space over time.

Files to upgrade / merge


  • Bin/
  • App_Browsers/
  • App_Code/
  • App_Data/ (This folder may not exist in your previous version. It needs to be added even if empty as ommiting it can cause issues with certain packages. In particular the XSLTsearch package will break without this folder)
  • Umbraco_client/
  • Install/
  • Umbraco/ (There are some exceptions to overwritting this folder. See below in the 'Merge' section.)


  • web.config
  • Config/ folder (All files in this folder should be merged if different, there may also be additional config files in your solution that need to be kept)
  • Umbraco/images/tray/tray.png (There are probably changes to this image if Umbraco has a custom section added. Don't replace it with the default one.)
  • Umbraco/images/​umbraco/sprites.png (There are probably changes to this image if Umbraco has a custom section added. Don't replace it with the default one.)
  • Umbraco/css/umbracoGui.css (There are probably changes to this stylesheet if Umbraco has a custom section added. Don't replace it with the default one.)
  • Umbraco/config/  (All files in this folder should be merged if different, pay particular attention to the en.xml file if packages such as Contour are installed.)
  • Views/
  • Global.asax


  • ​​Bin/App_global.asax.dll (Also delete reference in VS if it is there.)
  • Config/formhandlers.config

Useful Links:

Upgrades in general: http://our.umbraco.org/documentation/Installation/Upgrading/general​ ​

Version specific upgrades: http://our.umbraco.org/documentation/Installation/Upgrading/version-specific ​

Umbraco releases: http://our.umbraco.org/download​​

Nice / Usefull packages that you should install:

Sharron Martin

Author: Sharron Martin
Published: 01/10/2013

Tags: Upgrade; Umbraco;