How to migrate an old Flutter project to the current version

Migrating an old Flutter project to the current version is not just a matter of running flutter upgrade and fixing the error messages one by one. The project's Flutter and Dart versions, its plugins, the Android build tools and the iOS configuration all depend on each other. Changing everything at once makes it hard to tell which change caused a problem. In a controlled upgrade, you first record the current state, then make one small change and observe the result.

Having a backup of the code and a clean working branch in version control before the upgrade makes it easy to roll things back. Also document how the production build is produced. In older projects, the tool versions on the developer's machine may differ from those on the CI server or the machine that submits to the stores. Making these differences visible reduces surprises during the migration.

Start by documenting the current state

Note the Flutter SDK version, the Dart version, the channel in use and the build commands. Keep the package constraints in pubspec.yaml and the lock file. On the Android side, identify the Gradle Wrapper version, the Android Gradle Plugin and the Kotlin configuration. On the iOS side, record the Xcode version, the CocoaPods setup and the minimum iOS target. This information serves as a reference when you need to roll back to the old version or compare a build error.

Next, use the following command to see the state of your packages:

flutter pub outdated

The output shows the difference between the resolved version and the newer versions that are allowed or published. You don't need to adopt every new version right away. Some packages may be incompatible with your app's constraints, the Flutter version you use or another package. Remove dependencies that are no longer used as well. Upgrade packages one at a time or in small groups, and test the related screens and flows. If a large package change triggers many build errors at once, tracing the cause becomes difficult.

Break the Flutter SDK upgrade into small steps too. If the project is very old, building and fixing it on intermediate SDK versions can be more manageable than one long jump. Read the changed warnings and configuration requirements at each step. Don't move on to the next major change until a step builds successfully. Keep a clear version control history across the source code and package files.

Handle the Android configuration separately

For the Android build, the Gradle Wrapper, the Android Gradle Plugin and the Kotlin plugin must be compatible with each other. Updating one can change the requirements of the others. So review the versions in the project together and follow the Android project structure that Flutter documents for the SDK you are using. Don't pick a version just because it is new; verify its compatibility with your Flutter version, Android Studio and plugins.

In older projects, Gradle plugins may be applied with apply plugin and separate apply from lines. Newer project templates mostly use the plugins DSL approach. During the migration, check carefully where plugin definitions should be declared, in what order the Flutter Gradle plugin is introduced and how project-level settings should be moved. This is not just copying lines somewhere else; the division of responsibilities between settings.gradle and the app module's Gradle file may also change.

Even if the Android build succeeds, open the app on a real device. Notification permissions, file access, background tasks, deep links and the plugins you use can behave differently depending on the Android version. An emulator is useful, but it does not represent all the device conditions your app will face once it is in the store.

Review the iOS target and CocoaPods

On the iOS side, the minimum platform target in the Podfile must be consistent with the Xcode project settings. A Flutter version or plugin may require a newer minimum iOS version. Before raising the target, consider your existing users' devices and the packages you use. Choosing an unnecessarily high baseline can drop support for older devices, while a target that is too low can prevent dependencies from building.

Installing and resolving CocoaPods dependencies is also part of the upgrade. Before editing Pod files by hand, understand how these files are generated in the project and whether they are checked into version control. Errors during pod install are often related to the iOS deployment target, the Xcode toolchain or a plugin's requirements. To find the source of the problem, look at the pod and target information in the error message.

Fix deprecated APIs in a controlled way

You can use dart fix --apply to apply some of the code changes suggested by the Dart tooling. Run the command while the project builds, and review the changes it makes. This tool does not automatically resolve every API change or business logic issue. Don't accept the suggested changes without testing them; sweeping automated fixes can change what a call is meant to do.

After each step, both build the app and run through the core workflows on a real device. Check the features you use, such as sign-in, creating records, the camera, location, file picking, notifications and payments. The upgrade isn't finished just because the app launches. Plugin permissions, background behavior and store configuration can also be affected.

Before submitting to the stores

For a final check, create a separate release build and confirm that it can be produced in a clean environment. Make sure the version number, signing settings, privacy disclosures, permission texts and store images are up to date. Recheck the targeted range of devices and operating system versions for Android and iOS. Also leave the changes made to configuration files during the upgrade in a state your team can understand and explain.

As a first step, gather the project's current Flutter, package, Gradle, Kotlin, Xcode and CocoaPods status in a one-page note. Then open a separate upgrade branch in version control, change only one step and verify the build on a real device.