Illustration of a laptop with the Android on the screen and other tech objects in the background.

Migrating to AndroidX: tips, tricks, and guidance

Take advantage of the latest Jetpack has to offer.

Nick Anthony
Mar 25, 2020 · 7 min read

Jetpack is a set of libraries, tools, and guidance to help you write high-quality apps more easily. Jetpack makes coding easier through best practices, limiting boilerplate code, and simplifying complex tasks. All with the goal of enabling you to focus on the code that you really care about.

AndroidX is the package name for all the libraries within Jetpack. Think of AndroidX as the open-source project used to develop, test, version, and release Jetpack libraries.

Back at I/O 2018, we announced that Support Library would be refactored into the AndroidX namespace, which was completed with Support Library 28 and the announcement of AndroidX 1.0.

Why migrate?

  1. The Android Support Library has reached the end of its life. 28.0 was the last release of the Android Support namespace and the namespace is no longer maintained. So, if you want bug fixes or new features that would have previously gone into the Support Library, you need to migrate to AndroidX.
  2. Better package management. With AndroidX, you get standardized and independent versioning, as well as better standardized naming and more frequent releases.
  3. Other libraries have migrated to use the AndroidX namespace libraries, including Google Play services, Firebase, Butterknife, Mockito 2, and SQLDelight among others.
  4. All new Jetpack libraries will be released in AndroidX namespace. So, for example, to take advantage of Jetpack Compose or CameraX, you need to migrate to the AndroidX namespace.

Preparing to migrate

  • back up your project. If you’re using source control tools, it is still recommended that you make a backup, because migration will change many of the files in your project.
  • create a new branch on which to make the migration changes.
  • if possible, suspend or minimize development (at least don’t try to do refactoring or pull in new features) during the migration, as this will help reduce the number of merge conflicts that could happen.

Migrate

Step 1: Update to Support Library version 28

It is, therefore, recommended that you update to version 28, address all of the API changes, and ensure your app compiles with version 28.

Support Library version 28 and AndroidX 1.0 are binary equivalent, meaning that only the package name changes between those two versions: all the APIs are the same. This means that you should have very little to fix when migrating from 28 to AndroidX.

Step 2: Enable Jetifier

To enable Jetifier in your app, add the following to your gradle.properties files:

android.useAndroidX=trueandroid.enableJetifier=true

Now, when code auto-completion import libraries, you’ll import the AndroidX version of that library instead of the old Support Library version.

Step 3. Update dependencies

If you’re using a code generation library, Jetifier won’t modify these. So you will need to check that the code generation library is compatible with AndroidX.

If you consider skipping steps 2 and 3 here are some of the errors you could encounter:

  • the third-party code you’re using is not compatible with AndroidX. In this case, a stack trace similar to the one below will show you that it’s trying to pull in the old version of the Support Library:
Error : Program type already present: android.support.v4.app.INotificationSideChannel$Stub$Proxy |Reason: Program type already present: android.support.v4.app.INotificationSideChannel$Stub$Proxy
  • if you have a project that’s partially migrated, you might get a duplicate class error, where it’s trying to pull in the same code from both the Support Library and AndroidX. The stack trace will show you something like this:
Duplicate class android.support.v4.app.INotificationSideChannel found in modules classes.jar (androidx.core:core:1.0.0) and classes.jar (com.android.support:support-compat:28.0.0)

Step 4: Update your source code

  • Android Studio
  • manual update
  • Bash script

If you use Android Studio 3.2 stable or above, you can update your source code using the Migrate to AndroidX option on the Refactor menu. This is the recommended way as Android Studio can examine your source code to make correct decisions when refactoring.

If you don’t use Android Studio or employ a more sophisticated app architecture that the Migrate to AndroidX option doesn’t cover, you should instead leverage the class mapping csv file to implement a find and replace bash script. This script should find all source code instances of the android.support classes and then replace them with their AndroidX equivalent.

More concretely, the script should take the CSV file that provides the class mapping and then run a grep command followed by a sed command to replace the package names. However, because this is a brute force approach to migration, this basic find and replace may not sufficiently or correctly complete the migration.

Additionally, the update can also be done manually.

If you decide to take the manual approach, visit the Migrate to AndroidX page, where you can find an artifact mapping that details the Support Library packages and their corresponding class mapping is AndroidX. You can also download the CSV file from this page.

And that’s it, you should now have a project that compiles and uses AndroidX.

Those pesky exceptions

Version configuration files

ext.versions = [    ‘drawer’ : ‘28.0.0’,    ‘rview’ : ‘28.0.0’]implementation “com.android.support:drawerlayout:${versions.drawer}”implementation “com.android.support:recyclerview-v7:${versions.rview}”

Then, after running the migration tool you end up with this:

ext.versions = [    ‘drawer’ : ‘28.0.0’,    ‘rview’ : ‘28.0.0’]implementation “androidx.drawerlayout:drawerlayout:1.0.0”implementation “androidx.recyclerview:recyclerview:1.0.0”

DrawerLayout and RecyclerView are using the AndroidX packages, but the version numbers are now inline. Also, the versions variable numbers have not been changed. So you’ll need to do a manual update to this:

ext.versions = [    ‘drawer’ : ‘1.0.0’,    ‘rview’ : ‘1.0.0’
]
implementation “androidx.drawerlayout:drawerlayout:${versions.drawer}”implementation “androidx.recyclerview:recyclerview:${versions.rview}”

ProGuard and build scripts

Get the latest stable version

implementation ‘com.android.support:appcompat-v7:28.0.0’

And after migration, you would be using the alpha version of the corresponding AndroidX library:

implementation ‘androidx.appcompat:appcompat:1.1.0-alpha01’

So, if you prefer to use the stable version of the library, you’ll need to manually update the version:

implementation ‘androidx.appcompat:appcompat:1.0.2’

More help and resources

Elsewhere, there is also an article detailing the migration to AndroidX in the Plaid example project.

And finally, there is an issue tracker where you see the migration tool issues that the team is working on. You can, of course, report any issues you find with the migration tool here using the button at the top left of the page.

Final thoughts

Do you have thoughts on AndroidX? Let us know in the comments below or tweet using #AndroidStudio and we’ll reply from @AndroidDev, where we regularly share news and tips on how to be successful on Android.

Android Developers

The official Android Developers publication on Medium

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store