(small) Updates and (minor, major) Upgrades

Types of Upgrades

Windows Installer supports three types of product upgrades: small updates, minor upgrades, and major upgrades. The three types of upgrades are defined as follows.

A small update
consists of product changes, such as hot fixes, so small that no change to the product version is necessary or desired. (A drawback to small updates is that external programs, including installers for later versions of your product, will not be able to distinguish a product with the small update applied from one without the small update.)
A minor upgrade
is a change to the product large enough to merit a change to the product version, such as updating version 1.1 to 1.2, but in which there have been no significant changes to the setup organization between versions. The install-time behavior of a minor upgrade is to install over the existing product.
A major upgrade
includes substantial product changes, such as updating version 1.2 to 2.0. A major upgrade can contain significant changes to the setup architecture. The install-time behavior of a major upgrade can be to uninstall the earlier version and install the new one, or to install over the earlier version and then remove any leftover data.

For an earlier product version that was installed with a legacy (non-MSI) setup, a custom action will normally be required to uninstall or modify the existing product installation.
An upgrade can be packaged for deployment to the target system as a full installation (MSI package). An upgrade packaged as a full installation can be authored (using custom actions, command-line switches, or a setup launcher) to upgrade an existing product if one is present, or otherwise to behave as a first-time installation.

An upgrade can also be packaged as a Windows Installer patch file (a file with the MSP extension). A Windows Installer patch contains changes between the files (and other data) and MSI tables in the earlier and later versions. The file differences stored in a patch can be binary, byte-level differences, possibly resulting in a much smaller deliverable than an update packaged as a full installation package. An update that you package as a patch file can be used only to upgrade an existing, installed product, and cannot be used as a first-time installation.

Small updates and minor upgrades are commonly packaged as patches, while major upgrades are usually packaged as full installation packages.

A common misapprehension is that patches are a separate type of upgrade, as opposed to a packaging mechanism. In fact, the patch-development process involves first designing a minor or major upgrade, and then packaging it as a patch. Before creating a patch, it is recommended you test the update as a full installation package.

Deploying Upgrades and Patches

When you run an MSI installation package for the first time on a given system, Windows Installer caches the MSI database in the “super-hidden” directory %WINDIR%\Installer. By default, when you run the same package a second or later time on the same system, Windows Installer runs the package in maintenance mode, using the cached database. (A package is typically authored to show a different series of dialog boxes for first-time installations and maintenance-mode installations, using conditions such as “Not Installed”.)

During the initial installation, the MSI database is cached on the user’s system, but the product’s data files are not. If a maintenance operation results in a file having to be installed, MSI will require access to the original installation source, prompting the user to locate the source if it cannot be found (for example, if the installation was performed from a CD-ROM that is no longer in the drive). For this reason, you should either build a release with the MSI database external to a setup launcher, or create a setup launcher that caches the installation on the local machine.

Designing an Update-Friendly Installation

The design of your installation projects - the organization of a product’s features, components, and key paths - has an impact on the effectiveness of future updates. The effectiveness of an upgrade or patch is gauged by the following:
  1. Whenever possible, use versioned key files.
  2. Partition your product into discrete sets of features.
  3. Put user-configurable registry data in its own feature.
  4. MSI property values are not automatically saved during the initial installation.
  5. New subfeatures should be marked as “required” and “follow parent”.
  6. If your minor upgrade removes data (files, registry settings, and so forth) from a component, populate the corresponding “Remove” data.
  7. Change the MSI product version for each new release.
  8. When building your update package, use Patch Optimization in your build settings.
  9. When generating a patch for a compressed installation, use an administrative image.
  10. When generating a patch, both versions should have the same media layout.



Major version number, for example "1" in the version
It contains extensive new functions and is a new development based on the previous version.


Minor version number, for example "0" in the version
Updated software with extensive enhancements to existing features and few new features. The Windows product code remains unchanged.


Issue number, for example "2" in the version
Service Pack or Support Update is a software update with detail improvements and bug fixes. With the service pack the build number is increased and in depending on the extent of the improvement the revision number.


Compilation number, for example "444" in the version
Patch, also known as a hotfix or a quickfix, is an update that is released for troubleshooting or that often includes a new / improved feature that is urgently needed by a user (customer patch). The patch only increases the build number.

Package Code

Part of the Summary Information Stream, the package code identifies a particular database. The package code is not a Windows Installer property. Any two .msi databases with identical package codes must have identical contents. Therefore, you should change the package code for each build.


This is a Windows Installer property that identifies the product version. Note that Windows Installer uses only the first three fields of the ProductVersion property for version comparisons. For example, for a product version of, the 4 is ignored. (Note that this is true for comparisons of ProductVersion values, and not for file versions.)


This is a Windows Installer property that identifies the GUID of a product. Windows Installer treats two products with different ProductCode GUIDs as unrelated, even if the values for the ProductName property are the same.


This is a Windows Installer property that identifies the GUID that represents a related set of products. The UpgradeCode should be consistent across different versions and languages of a family of related products so that it can be used to search for related versions of the product that are already installed. You can set the UpgradeCode for an upgrade in the Upgrades view.

Major Upgrade vs. Minor Upgrade vs. Small Update

Requirement for the Upgrade Use a Major Upgrade? Use a Minor Upgrade? Use a Small Update? Note
Change the name of the .msi package Yes No No The default file name is taken from the Product Name property, provided the .msi file is not compressed in a Setup.exe installation launcher.
Enable end users to install earlier versions and the latest version on the same machine Yes No No
Add a new subfeature Yes In some cases In some cases If the new subfeature consists of new components only, you can use a small update, a minor upgrade, or a major upgrade. If the new subfeature consists of existing components, you must use a major upgrade.
Move or delete a feature in the product tree Yes No No
Add a new component to a new feature Yes Yes Yes
Add a new component to an existing feature Yes Yes Yes
Move or delete a component in the product tree Yes No No
Change the component code of an existing component Yes No No
Change the key file of a component Yes No No
Add, remove, or modify any of the following: files, registry keys, or shortcuts Yes Yes Yes If the file, registry key, or shortcut is in more than one component and the component is shared by two or more features, a major upgrade must be used.
Start with an MSI Database or Transform project Yes No No

Codes that Need to Be Changed for the Different Types of Upgrades

Package Code Product Version Product Code Upgrade Code
Small Update ❲✘❳
Minor Upgrade ❲✘❳ ❲✘❳
Major Upgrade ❲✘❳ ❲✘❳ ❲✘❳