Version Upgrades and Migrations
This section covers version-based upgrades and the required migration effort for Shopware core and extensions. When upgrading to a new minor or major Shopware version, review it to understand breaking changes, required adjustments, and compatibility requirements.
Scope of this section
Upgrades typically fall into one of these categories:
- APIs: HTTP/API contract changes.
- Core: Framework-level changes, data abstraction layer (DAL) updates, APIs, feature removals, and backend behavior.
- Administration: frontend framework upgrades, Vue upgrades, breaking changes.
- Storefront: breaking changes related to Twig templates and JavaScript plugins.
- App System: changes that affect the app framework (e.g. manifest, webhooks, etc.).
- Hosting & Configuration: for infrastructure-related changes.
INFO
Administration framework upgrades (Vue, Pinia, Vite, Meteor) may introduce breaking changes requiring major version updates for affected plugins.
Typical Shopware upgrade workflow
When targeting a new Shopware version:
- Review release notes and UPGRADE files
- Check breaking changes per layer (Core / Admin / Storefront / API)
- Validate extension compatibility
- Apply required migrations
- Rebuild Admin/Storefront assets if needed
- Test critical flows
- Update extension versions if required
Upgrade impact in real projects
Upgrade complexity depends on the installation:
- Heavy custom code increases migration effort.
- No custom code but 60 Store plugins can be equally complex.
- Most real-world projects fall somewhere in between.
A consistent architecture, centralized CI, and controlled extension strategy help you get ahead of upgrade pain.
Custom projects
- Follow the (Performing updates guide) to stage, test, and execute upgrades in order.
- Review RELEASE_INFO and UPGRADE files (example) per release.
- Use feature toggles to decouple risky changes from the deployment.
Upgrade strategy for extension developers
To reduce long-term upgrade cost:
- Avoid internal APIs and undocumented features
- Keep dependencies aligned with Shopware core
- Maintain automated test coverage
- Keep database migrations idempotent
- Track deprecations continuously—do not batch them
Custom plugins
- Provide migration code for schema/config changes.
- Ship defaults that work on older core versions until you deliberately drop support.
- Test against the target Shopware version matrix before rollout; note breaking changes in the plugin README.
Store plugins
- Align Store metadata (compatibility range, changelog) with the tested core versions; refuse installation on unsupported versions.
- Run Shopware Store validation on the new build before submission (Store submission via CLI).
- Communicate BC breaks explicitly.
- Prefer additive changes and feature flags to keep existing shops stable.
Apps
- Version manifests carefully. Broaden compatibility only after testing, and narrow it when deprecations apply.
- Keep webhook/action handlers tolerant to new fields and events. Avoid hard coupling to specific core patch behavior.
Next steps
For the operational update procedure, continue with Upgrade Shopware.
For general development best practices that reduce upgrade friction, see the Development guide.
