Use the Android Gradle plugin Upgrade Assistant

Stay organized with collections Save and categorize content based on your preferences.

The Android Gradle plugin (AGP) Upgrade Assistant is a tool in Android Studio that helps you upgrade the version of AGP used by your project.

We regularly release AGP changes related to new features for configuring your build, new APIs for use by other Gradle plugins, and refining the integration of the project build with Android Studio. Upgrading the version of AGP used by your project allows you to benefit from the latest features.

What is the AGP Upgrade Assistant used for?

The AGP Upgrade Assistant helps guide you through the changes needed to upgrade AGP versions. The following are the most common use cases for the Upgrade Assistant:

  • Syntax changes: The Upgrade Assistant attempts to translate your build files for an older version of AGP to those needed for a newer version of AGP. As we develop AGP, we update build files to support interfaces as they are replaced, deprecated, or unsupported over time.

  • Compatibility requirements between AGP and Gradle: The Upgrade Assistant is aware of the compatibility requirements between AGP and Gradle, and helps ensure that you are using the version of Gradle required for your version of AGP.

  • Compatibility requirements between AGP and third-party Gradle plugins: The Upgrade Assistant is aware of the compatibility requirements between AGP and some third-party Gradle plugins, and helps ensure that you are using versions of third-party Gradle plugins required for your version of AGP.

In general, the Upgrade Assistant aims to remove some of the need for trial-and-error changes to build files, or guesswork about the meaning of error messages after upgrade, and also explains why the changes that it is proposing are necessary.

How to use the AGP Upgrade Assistant

To use the Upgrade Assistant, make sure your project structure accommodates it, and then run it from Android Studio, as described below.

Setup

Before you run the Upgrade Assistant, make sure your project is properly formatted and backed up.

Structure your project using the Gradle build files and domain-specific language

The AGP Upgrade Assistant has the best chance of working if you do the following:

  • Configure the build using the Gradle build files: The Upgrade Assistant relies on static analysis of the Gradle build files. To get the most out of the Upgrade Assistant, you should configure your build using these build files. Note that the Upgrade Assistant does not support projects that use buildSrc to define constants and variables used in the build files. In general, we do not recommend using buildSrc to structure your project because it can be inefficient: any change to buildSrc constants and variables, no matter how minor, triggers a full rebuild of the project.
  • Use the declarative build domain-specific language: Gradle build files are expressed in full programming languages, Groovy and/or Kotlin; however, the more declarative the expression of the project configuration, the more likely it is that the Upgrade Assistant will successfully find all the places that need adjustment for an upgrade.

Even if a project does not run against these limitations, the Upgrade Assistant might still fail to perform a clean upgrade. See Troubleshooting for guidance on how to resolve or report bugs.

Back up your project

Before starting to use the Upgrade Assistant, we recommend that your project has no uncommitted changes as seen by your version control system. If you're not using version control, we suggest taking a backup of a last known good version at this point.

After the Upgrade Assistant runs and the project is successfully built and tested, you can commit the new version of the project to your version control system.

Run the Upgrade Assistant

To run the Upgrade Assistant, follow these steps:

  1. Launch the Upgrade Assistant from the notification prompt or by navigating to Tools > AGP Upgrade Assistant... The tool window that appears displays the details of the default upgrade from the project's current version of AGP to the latest version supported by this version of Android Studio.
The AGP Upgrade Assistant tool window when launched, and the notification prompt.
Figure 1. The AGP Upgrade Assistant tool window when launched, and the notification prompt.
  1. Check the required and recommended steps. In the left-hand panel, there is a tree with checkboxes that details individual steps in the upgrade, categorized by whether they are required or recommended to update, and whether they are prerequisites of other steps or not. Select individual items in the tree to display more details about each step in the main panel.

  2. Run the upgrade by selecting the steps required or desired and clicking Run selected steps. The Upgrade Assistant will make changes to the project build files, and attempt to sync the new project build with Android Studio. This may take a while if you have numerous modules, as new versions of plugins and libraries may need to be downloaded.

  3. Once the project has successfully synced with Android Studio, build the project and run test suites to verify that the upgrade operation has not changed any functionality.

  4. Once you have verified that your project is in a good state, commit the new version of your project to your version control system.

Troubleshooting

If the Upgrade Assistant offers an upgrade, but the upgrade fails (typically by making changes to the build files which result in a sync failure), there are steps that you can take to help isolate and fix the error.

  • First, inspect the error that led to the sync failure. Sometimes, the error will have a clear cause, which you can address in the project's build files.

  • If the error message is not clear, or it's not obvious what is causing the problem, then it's time to return the project to its original state to break the upgrade down into smaller steps. Restore the original state from version control, or from backups, and make sure the project (in its original state) is once more synced with Android Studio. Then you can investigate using the following two kinds of upgrade breakdowns:

    • Upgrade to a version of AGP that is not the latest version. If the upgrade that went wrong was an upgrade of a large number of versions, the best way to make progress and to help isolate the problem is to do a series of smaller upgrades, from version to version, to find the first upgrade that triggers the problem.
    • Within an upgrade, do individual steps one at a time. Once you have found an upgrade between successive versions of AGP that triggers the problem, it might be possible to turn individual steps in the upgrade off. If it is, try doing each step one at a time, to find which of those steps is responsible. If you can’t find the step responsible, it's worth checking the release notes of any other Gradle plugins you are using for any compatibility issues with Gradle or AGP; sometimes, there will be a new release to address the use of deprecated or internal APIs.
  • Report a bug. Sometimes all the preparatory steps and sync succeed, and the final upgrade step still fails. In this case, please report a bug.

Even if you do succeed in fixing the error yourself, please still report the original failure to the bug tracker, so that the problem can be addressed by the development team.