Skip to content

Clean up and fixes for migrate-to-built-in-kotlin guides #13563

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sfshaza2 merged 1 commit into from
Jul 8, 2026
+132 −98
Merged

Clean up and fixes for migrate-to-built-in-kotlin guides #13563

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 80 additions & 60 deletions ...ntent/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,34 +4,43 @@ description: >-
Migrate Flutter apps to use built-in Kotlin.
---

## Migrate

This guide outlines the migration steps specifically for app developers.

These instructions assume you are updating from
an AGP version created before 9.0.0 to an AGP version 9.0.0+.
You should also use the minimum compatible dependency versions
listed in the [Android Gradle Plugin docs][AGP block].

### Verify flags in properties file
:::note
To update Flutter plugins to use built-in Kotlin,
follow the [migration guide for plugin authors][].
:::

[AGP block]: {{site.android-dev}}/build/releases/gradle-plugin
[migration guide for plugin authors]: /release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors

<a id="verify-flags-in-properties-file" aria-hidden="true"></a>

## Verify flags in the Gradle properties file

Flutter sets the default behavior to use the legacy Kotlin Gradle Plugin (KGP)
and the old AGP DSL types to support projects that have not yet migrated.
and the old AGP DSL types to support projects that haven't yet migrated.
The Flutter migrator tool automatically adds `android.builtInKotlin=false`
and `android.newDsl=false` to your `gradle.properties` file.

If these flags are missing from your `gradle.properties` file,
the Flutter tool automatically adds them when you next build or run your app
using `flutter run` or `flutter build apk`.
the Flutter tool automatically adds them when you
next build or run your app using `flutter run` or `flutter build apk`.

Alternatively, building the project using Android Studio tooling also adds
these flags automatically.
Alternatively, building the project using Android Studio tooling also
adds these flags automatically.
Once the process completes, verify that the flags have been added.
For more details, see [Issue #183910].
For more details, see Flutter [issue #183910][issue-183910].

All add-to-app projects must manually add `android.builtInKotlin=false`
and `android.newDsl=false` to the Android host app's `gradle.properties` file.
The Flutter migrator tool cannot run during add-to-app Android host app builds
All add-to-app projects must manually add
`android.builtInKotlin=false` and `android.newDsl=false` to
the Android host app's `gradle.properties` file.
The Flutter migrator tool can't run during add-to-app Android host app builds
because the host app is a pure native Android project.

```properties diff title="<host-app-project>/gradle.properties"
Expand All @@ -42,26 +51,26 @@ because the host app is a pure native Android project.

:::note
If your app doesn't apply
the `kotlin-android` plugin (also called Kotlin Gradle Plugin),
then you only need to add `android.newDsl=false` and do not need
further migration.
the `kotlin-android` plugin (also called the Kotlin Gradle Plugin),
then you only need to add `android.newDsl=false` and
don't need to complete any further migration steps.
:::

### Update the Gradle file
## Update the Gradle file

First, find the `kotlin-android` plugin (or the `org.jetbrains.kotlin.android`
plugin).
First, find the `kotlin-android` plugin
(or the `org.jetbrains.kotlin.android` plugin).
It is likely located in the `plugins` block of the
`<app-src>/android/app/build.gradle` or the
`<app-src>/android/app/build.gradle.kts` file.
If you use the legacy `apply` syntax, it will be located in
the Groovy-based `<app-src>/android/app/build.gradle` file, as this syntax is
not supported in Kotlin DSL.
the Groovy-based `<app-src>/android/app/build.gradle` file,
as this syntax is not supported in Kotlin DSL.

The following examples demonstrate how to migrate a Flutter Android app
and an add-to-app Android host app:
The following examples demonstrate how to
migrate a Flutter Android app and an add-to-app Android host app:

#### Migrate your Flutter Android app
### Migrate your Flutter Android app

<Tabs key="modern-legacy-apply">
<Tab name="plugins block">
Expand Down Expand Up @@ -173,6 +182,7 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block:
// ...
}
```

Add the `kotlin.compilerOptions{}` DSL block with the following:

```groovy diff title="<app-src>/android/app/build.gradle"
Expand Down Expand Up @@ -207,7 +217,7 @@ kotlin {
</Tab>
</Tabs>

#### Migrate your add-to-app Android host app
### Migrate your add-to-app Android host app

Android native apps use the `alias` keyword to apply plugins,
which is incompatible with the legacy `apply()` syntax.
Expand Down Expand Up @@ -250,6 +260,7 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block:
// ...
}
```

Add the `kotlin.compilerOptions{}` DSL block with the following:

```kotlin diff title="<app-src>/android/app/build.gradle.kts"
Expand Down Expand Up @@ -283,75 +294,84 @@ kotlin {
// ...
```

### Validate
## Validate

Execute `flutter run` or `flutter build apk` to confirm that
your app builds and launches on a connected Android device or emulator.
Execute `flutter run` or `flutter build apk` to
confirm that your app builds and
launches on a connected Android device or emulator.

If your app fails to build because you are using an unmigrated Flutter plugin,
If your app fails to build because
you are using an unmigrated Flutter plugin,
follow the instructions below:

### Report incompatible Kotlin Gradle Plugin usage to plugin authors
## Report incompatible Kotlin Gradle Plugin usage to plugin authors

Follow these instructions only if your app uses a Flutter plugin
that has not yet migrated to built-in Kotlin.
that hasn't yet migrated to built-in Kotlin.

1. Find the repository of the unmigrated Flutter plugin by searching for the
plugin name on [pub.dev](https://pub.dev) or online.
2. Refer to the plugin CHANGELOG to confirm that no existing version
has migrated to built-in Kotlin.
3. Report an issue to the plugin authors, informing them that the Kotlin
Gradle Plugin is incompatible and won't be supported in a future version
of Flutter.
1. Find the repository of the unmigrated Flutter plugin by
searching for the plugin name on [pub.dev]({{site.pub}}) or online.
1. Check the plugin's changelog to confirm that
no existing version has migrated to built-in Kotlin.
1. Report an issue to the plugin authors,
informing them that the Kotlin Gradle Plugin is incompatible and
won't be supported in a future version of Flutter.

You can use the following template for the issue:

**Issue Title:** Migrate Plugin to Built-in Kotlin
**Issue Title:** Migrate plugin to built-in Kotlin

**Issue Body:**

```markdown
I am using `<plugin-name>` in my Flutter app.

Starting with Android Gradle Plugin (AGP) 9.0,
support for applying the Kotlin Gradle Plugin (KGP) has been removed.
Because this plugin applies KGP, it causes a compilation error
that prevents my app from building.
Here is an example of the error [Issue #181383][].
Because this plugin applies KGP,
it causes a compilation error that prevents my app from building.
Flutter [issue #181383](https://github.com/flutter/flutter/issues/181383)
includes an example of the error.

Flutter has temporarily added support to allow KGP
while apps and plugins migrate to AGP 9.0+,
while apps and plugins migrate to AGP 9.0 or later,
but this support will be removed in a future version of Flutter.

Please migrate this plugin to use built-in Kotlin to ensure your plugin
users can successfully build their apps in future versions of Flutter.
Please migrate this plugin to use built-in Kotlin to
ensure your plugin users can successfully
build their apps in future versions of Flutter.

Here is the Flutter [migration guide for plugin authors][plugin-migration-guide].
Here is the Flutter
[migration guide for plugin authors](https://docs.flutter.dev/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors).
```

Please be respectful and mindful of the plugin repository's rules and code
of conduct when reporting issues and interacting with plugin authors.
Please be respectful and mindful of the
plugin repository's rules and code of conduct when
reporting issues and interacting with plugin authors.

For reference, see the [Flutter Code of Conduct][Code of Conduct].

[Code of Conduct]: {{site.repo.flutter}}/blob/main/CODE_OF_CONDUCT.md

## Next steps

See the [migration overview](./) for next steps.
For next steps,
see the [built-in Kotlin migration overview][migration-overview].

[migration-overview]: /release/breaking-changes/migrate-to-built-in-kotlin

## References

Relevant issues:

- [Issue #183910][]: Add Disable Built-in Kotlin and new DSL Migrators
- [Issue #181383][]: Flutter plugins should support AGP 9.0.0
- [Issue #183910][issue-183910]: Add Disable Built-in Kotlin and new DSL Migrators
- [Issue #181383][issue-181383]: Flutter plugins should support AGP 9.0.0

The Gradle build files in your app vary based on the Flutter version
used when your app was created.
The Gradle build files in your app vary based on
the Flutter version used when your app was created.
Consider staying up to date with the latest version
of the build files by periodically running `flutter upgrade`
in your app's directory.

[AGP block]: {{site.android-dev}}/build/releases/gradle-plugin

[Issue #183910]: {{site.github}}/flutter/flutter/issues/183910
[Issue #181383]: {{site.github}}/flutter/flutter/issues/181383
in your app's root directory.

[plugin-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors
[Code of Conduct]: https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md
[issue-183910]: {{site.repo.flutter}}/issues/183910
[issue-181383]: {{site.repo.flutter}}/issues/181383
Loading
Loading