Flutter 3.47: What to Check Before You Upgrade
Flutter 3.47 is the current stable release, and this update changes more than a version number. Material and Cupertino are available as standalone packages, Widget Previews are stable, Impeller is the default desktop renderer, and the platform baselines are moving forward.
Use this short checklist before running flutter upgrade on an older project.
The goal is to find migration work while it is still a controlled change—not
after it becomes a release blocker.
The five-minute summary
Check these areas before upgrading:
- decide whether to opt in to
material_uiandcupertino_uinow; - confirm that dropping iOS 13 and 14 is acceptable for your product;
- audit custom iOS lifecycle code for the
UIScenerequirement; - retry Swift Package Manager if the project previously disabled it;
- test web dependencies with Wasm and desktop rendering with Impeller;
- align the Android dependency versions used by local and CI builds.
Keep preparation, framework upgrade, and UI-package migration in separate commits. That gives every failure a smaller search area and preserves a clean rollback point.
1. Do not migrate UI packages by accident
Flutter 3.47 publishes version 1.0 of material_ui and cupertino_ui as
standalone packages. The framework-bundled Material and Cupertino libraries
still exist in this release, so opting in is a product decision rather than an
immediate requirement.
Moving the design systems to packages lets them ship on a different schedule from the Flutter SDK. That is useful, but it also means teams must decide how and when UI changes enter the app.
If you want to test the migration, use a separate branch and run:
dart fix --apply --code=migrate_design_widgets
Review the import changes, localizations, theme behavior, and third-party packages. Do not combine this migration with unrelated visual work.
2. Check your Apple deployment targets
Flutter 3.47 raises the supported minimums to iOS 15 and macOS 12. Before upgrading, inspect current store analytics and confirm that the users and devices you support fit those baselines.
Search the Xcode project, Podfile, build configuration, and CI overrides for older deployment targets. A target declared in more than one place can create confusing warnings or environment-specific failures.
3. Audit the iOS lifecycle
The iOS 27 SDK requires the UIScene lifecycle for UIKit-based applications.
The Flutter CLI can migrate standard projects automatically, but apps with a
custom AppDelegate or plugins tied to the legacy lifecycle may need manual
work.
Review custom code for:
- notification registration;
- deep links and universal links;
- authentication callbacks;
- background tasks;
- window and root-view-controller setup;
- SDK initialization performed only in
AppDelegate.
Test cold start, background-to-foreground transitions, and link handling on a real release build—not only during hot reload.
4. Re-check Swift Package Manager support
Flutter reports that most of the top iOS plugins have migrated to Swift Package Manager. If an older dependency forced your project back to CocoaPods, audit the package list again before assuming the blocker still exists.
Keep a list of the plugins that require CocoaPods, verify their current release notes, and test the migration in isolation. A dependency-manager change and a Flutter framework upgrade are easier to diagnose when they are separate.
5. Test Flutter web with Wasm
Flutter is moving toward WebAssembly as the default for web applications, but legacy JavaScript interop can still block a project. Run a production build:
flutter build web --release --wasm
If it fails, look for dependencies that still use dart:html or dart:js and
prefer versions that support package:web. Treat the first Wasm build as a
compatibility audit. Measure startup and runtime behavior before making a
deployment decision.
6. Verify desktop rendering
Impeller is now the default renderer on macOS, Windows, and Linux. Desktop apps should test animations, text rendering, custom shaders, embedded native content, and any screenshot or visual-regression baselines.
Temporary renderer opt-outs exist, but they are diagnostic tools rather than a long-term strategy. If the app must opt out, reduce the issue to a reproducible case and track the removal of the workaround.
7. Align the Android build matrix
The Flutter 3.47 release notes document a verified Android baseline that includes Java 17, Kotlin Gradle Plugin 2.4, Android Gradle Plugin 9.1, and Gradle 9.3.1. Older projects often override one or more of these values in build files or CI images.
Record the versions used locally and in CI, then remove unnecessary overrides where the Flutter SDK already provides standard variables. If the app or a plugin still applies the legacy Kotlin Gradle Plugin, follow the built-in Kotlin migration guidance before compatibility support is removed.
A safer upgrade sequence
- create clean Android, iOS, and web release-build baselines;
- remove unused packages and update critical plugins;
- align CI and local toolchain versions;
- upgrade Flutter without opting into unrelated migrations;
- run tests and release builds;
- migrate standalone UI packages, SwiftPM, or Wasm one at a time;
- test the important product flows on representative devices;
- release to an internal or small beta group first.
The most useful result of the checklist may be a decision to prepare first. Finding an incompatible plugin before changing the SDK is faster and safer than discovering it during a production release.