What went wrong (and right) while migrating a Qt Widgets app to QML
Over the last ~6 weeks I’ve been working on a fork of a Qt-based launcher, with a long-term goal of moving the UI from Qt Widgets to QML.
This week I finished what turned out to be the hardest part of the entire effort: backporting an ongoing QML migration into a live codebase without breaking existing workflows.
The current state is intentionally hybrid: - QML is now the primary UI path - Qt Widgets remain as a fallback for some flows - Architecture decisions are frozen, cleanup and edge cases are ongoing
What surprised me most is that the migration itself was not the main challenge — keeping the system buildable, testable, and reversible during the transition was.
Some things that helped: - Treating the hybrid phase as a first-class design state, not a temporary mess - Keeping widget code untouched until QML paths proved stable - Accepting that “migration complete” is a mindset shift, not a commit
The project is still early and releases are alpha-only for now. I plan to publish weekly alpha builds to gather feedback while continuing cleanup and packaging work.
If you’ve done large UI or architectural migrations in Qt (or elsewhere), I’d be very interested in lessons learned or mistakes to avoid.