Solution Import: Upgrade vs Update vs Patch 📦

When you import a newer version of a solution that’s already installed, Dataverse asks how to apply it. The option you choose decides one crucial thing: what happens to components that are no longer in the new version.

TL;DR: Upgrade rolls up all patches and deletes components no longer in the new version (clean, consistent). Stage for Upgrade does the same but defers deletion so you can migrate data first. Update replaces the solution but keeps removed components (fastest, but can leave orphans). Patch ships only additive changes to tables/assets on top of a parent; it can never remove components.

The import options at a glance

Option	Removed components	Speed
Upgrade (default)	Deleted	Slower
Stage for Upgrade	Deleted later	Slower
Update	Kept	Fastest
Patch	Can’t be removed	Fast

Upgrade

🔸 Upgrade is the default. It upgrades to the latest version and rolls up all previous patches in one step.

🔸 Any components in the previous version that aren’t in the new version are deleted, so the result is consistent with exactly what you shipped.

🔸 Choose Upgrade for a predictable, clean target that mirrors your source solution.

Stage for Upgrade

🔸 Stage for Upgrade upgrades to the higher version but defers the deletion of the old version and its patches.

🔸 It leaves both the old solution and a new _Upgrade solution installed side by side, so you can migrate data before finishing.

🔸 Complete it later by selecting the base solution and choosing Apply Solution Upgrade, which uninstalls the old solution/patches and deletes any components not in the new version.

📌 Note: recent platform optimizations mean the single-step Upgrade no longer needs a temporary _Upgrade solution or an uninstall of the original.

Update

🔸 Update replaces your solution with the new version but does not delete components that are missing from it; they remain in the system.

🔸 It has the best performance, typically finishing faster than the upgrade methods.

🔸 The trade-off: removed components become orphans, so source and target environments can drift apart. Use Update for speed when you accept that risk.

Patch

🔸 A patch contains only changes to tables and related table assets (columns, forms, views), not whole system components. It’s a lightweight, additive update on top of a parent solution.

🔸 Key rules: a patch has one parent (which can’t itself be a patch), you can only install it if the parent is present, and its version must share the parent’s major.minor but have a higher build/revision.

🔸 Patches are additive only, you can’t remove components with a patch. To remove components, do an Upgrade.

🔸 Patch protection must match its parent (managed patch needs a managed parent), and unmanaged patches shouldn’t be used for production. Eventually roll up patches into a new solution version.

Understanding version numbers

🔸 Versions are major.minor.build.revision. An update must have a higher major, minor, build or revision than the parent (for example base 3.1.5.7 to 3.1.5.8).

🔸 A patch keeps the same major.minor as its parent but a higher build/revision (for example parent 1.0 to patch 1.0.1.0).

Which should I choose?

flowchart TD
    A["Importing a newer solution version"] --> B{"Just a small, additive fix<br/>to tables/columns/forms?"}
    B -->|"Yes"| C["Patch"]
    B -->|"No, a full solution update"| D{"Need old + new installed<br/>together to migrate data?"}
    D -->|"Yes"| E["Stage for Upgrade,<br/>then Apply Solution Upgrade"]
    D -->|"No"| F{"OK to leave removed<br/>components as orphans?"}
    F -->|"Yes, speed matters most"| G["Update"]
    F -->|"No, want a clean,<br/>consistent target"| H["Upgrade"]

🔸 A clean, exact target that removes retired components calls for Upgrade.

🔸 Needing to keep old and new to migrate data first calls for Stage for Upgrade, then Apply Solution Upgrade.

🔸 A fast iterative change where orphans are acceptable calls for Update.

🔸 A small additive fix to a table without shipping everything calls for Patch.

⚠️ Watch out

🔸 Update never deletes. Components removed in your source stay behind in the target, so environments drift over time.

🔸 Patches can’t remove anything. If you need to delete a column/component, you must Upgrade.

🔸 Don’t leave a pending upgrade. A stuck _Upgrade solution blocks further upgrades/patches until it’s completed or deleted.

🔸 Managed vs unmanaged must match for upgrades and patches, you can’t upgrade across protection types.

🛠️ FAQ

What’s the difference between Upgrade and Update? Upgrade deletes components that are no longer in the new version (clean, consistent); Update keeps them (faster, but can orphan components).

When do I use Stage for Upgrade? When you need the old and new solutions installed at the same time to migrate data, then finish with Apply Solution Upgrade.

Can a patch delete a component? No, patches are additive only. Use an Upgrade to remove components.

What version number does a patch need? The same major.minor as its parent but a higher build/revision (for example parent 1.0 to patch 1.0.1.0).

🔗 Related

🔸 Managed vs Unmanaged Solutions, the protection types these options act on.

🔸 Power Platform Environment Types, where you promote solutions.

🔸 All Dataverse tips · Knowledge base overview

Details reflect Microsoft Learn at time of writing. Always confirm current behavior in the Microsoft Power Platform ALM documentation.