Skip to content

Most visited

Recently visited

navigation

Version Your App

Quickview

  • Your app must be versioned
  • Set the version in the app's Gradle build files
  • How you version your apps affects how users upgrade
  • Determine your versioning strategy early in the development process, including considerations for future releases.

In this document

  1. Set Application Version Information
  2. Specify API Level Requirements

See also

  1. Prepare for Release
  2. Launch Checklist for Google Play
  3. Configure Build Variants

Versioning is a critical component of your app upgrade and maintenance strategy. Versioning is important because:

The Android system does not use app version information to enforce restrictions on upgrades, downgrades, or compatibility of third-party apps. Instead, you are responsible for enforcing version restrictions within your app or by informing users of the version restrictions and limitations. The Android system does, however, enforce system version compatibility as expressed by the minSdkVersion setting in the build files. This setting allows an app to specify the minimum system API with which it is compatible. For more information see Specifying Minimum System API Version.

Set Application Version Information

To define the version information for your app, set values for the version settings in the Gradle build files. These values are then merged into your app's manifest file during the build process.

Note: If your app defines the app version directly in the <manifest> element, the version values in the Gradle build file will override the settings in the manifest. Additionally, defining these settings in the Gradle build files allows you to specify different values for different versions of your app. For greater flexibility and to avoid potential overwriting when the manifest is merged, you should remove these attributes from the <manifest> element and define your version settings in the Gradle build files instead.

Two settings are available, and you should always define values for both of them:

You can define default values for these settings by including them in the defaultConfig {} block, nested inside the android {} block of your module's build.gradle file. You can then override these default values for different versions of your app by defining separate values for individual build types or product flavors. The following build.gradle file shows the versionCode and versionName settings in the defaultConfig {} block, as well as the productFlavors {} block.

android {
  ...
  defaultConfig {
    ...
    versionCode 2
    versionName "1.1"
  }
  productFlavors {
    demo {
      ...
      versionName "1.1-demo"
    }
    full {
      ...
    }
  }
}

In the defaultConfig {} block of this example, the versionCode value indicates that the current APK contains the second release of the app, and the versionName string specifies that it will appear to users as version 1.1. This build.gradle file also defines two product flavors, "demo" and "full." Since the "demo" product flavor defines versionName as "1.1-demo", the "demo" build uses this versionName instead of the default value. The "full" product flavor block does not define versionName, so it uses the default value of "1.1".

The Android framework provides an API to let you query the system for version information about your app. To obtain version information, use the getPackageInfo(java.lang.String, int) method of PackageManager.

Note: When you use Instant Run, Android Studio automatically sets the versionCode to MAXINT and the versionName to "INSTANTRUN".

Specify API Level Requirements

If your app requires a specific minimum version of the Android platform, you can specify that version requirement as API level settings in the app's build.gradle file. During the build process, these settings are merged into your app's manifest file. Specifying API level requirements ensures that your app can only be installed on devices that are running a compatible version of the Android platform.

Note: If you specify API level requirements directly in your app's manifest file, the corresponding settings in the build files will override the settings in the manifest file. Additionally, defining these settings in the Gradle build files allows you to specify different values for different versions of your app. For greater flexibility and to avoid potential overwriting when the manifest is merged, you should remove these attributes from the <uses-sdk> element and define your API level settings in the Gradle build files instead.

There are two API level settings available:

To specify default API level requirements in a build.gradle file, add one or more of the settings above to the defaultConfig {} block, nested inside the android {} block. You can also override these default values for different versions of your app by adding the settings to build types or product flavors. The following build.gradle file specifies default minSdkVersion and targetSdkVersion settings in the defaultConfig {} block and overrides minSdkVersion for one product flavor.

android {
  ...
  defaultConfig {
    ...
    minSdkVersion 14
    targetSdkVersion 24
  }
  productFlavors {
    main {
      ...
    }
    afterLollipop {
      ...
      minSdkVersion 21
    }
  }
}

When preparing to install your app, the system checks the value of these settings and compares them to the system version. If the minSdkVersion value is greater than the system version, the system prevents the installation of the app.

If you do not specify these settings, the system assumes that your app is compatible with all platform versions.

For more information, see the <uses-sdk> manifest element documentation and the API Levels document. For Gradle build settings, see Configure Build Variants.

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.