Configure the app module

This page describes useful app settings in the module-level build.gradle file that you will likely want to toggle.

Set the application ID

Every Android app has a unique application ID that looks like a Java package name, such as com.example.myapp. This ID uniquely identifies your app on the device and in Google Play Store. If you want to upload a new version of your app, the application ID (and the certificate you sign it with) must be the same as the original artifact—if you change the application ID, Google Play Store treats the upload as a completely different app. So once you publish your app, you should never change the application ID.

Your application ID is defined with the applicationId property in your module's build.gradle file, as shown here:


android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 15
        targetSdkVersion 24
        versionCode 1
        versionName "1.0"


android {
    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 15
        targetSdk = 24
        versionCode = 1
        versionName = "1.0"

When you create a new project in Android Studio, the applicationId exactly matches the Java-style package name you chose during setup. However, the application ID and package name are independent of each other beyond this point. You can change your code's package name (your code namespace) and it will not affect the application ID, and vice versa (though, again, you should not change your application ID once you publish your app). However, changing the package name has other consequences you should be aware of, so see the section about how to change the package name.

And although the application ID looks like a traditional Java package name, the naming rules for the application ID are a bit more restrictive:

  • It must have at least two segments (one or more dots).
  • Each segment must start with a letter.
  • All characters must be alphanumeric or an underscore [a-zA-Z0-9_].

Note: The application ID used to be directly tied to your code's package name; so some Android APIs use the term "package name" in their method names and parameter names, but this is actually your application ID. For example, the Context.getPackageName() method returns your application ID. There's no need to ever share your code's true package name outside your app code.

Caution: If you are using WebView, consider using your package name as a prefix in your application ID; otherwise you might encounter problems as described in issue 211768.

Change the application ID for testing

By default, the build tools apply an application ID to your instrumentation test APK using the application ID for the given build variant, appended with .test. For example, a test APK for the build variant has the application ID

Although it shouldn't be necessary, you can change the application ID by defining the testApplicationId property in your defaultConfig or productFlavor block.

Change the package name

Although your project's package name matches the application ID by default, you can change it. However, if you want to change your package name, be aware that the package name (as defined by your project directory structure) should always match the package attribute in the AndroidManifest.xml file, as shown here:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android=""
    android:versionName="1.0" >

The Android build tools use the package attribute for two things:

  • It applies this name as the namespace for your app's generated class.

    Example: With the above manifest, the R class will be com.example.myapp.R.

  • It uses it to resolve any relative class names that are declared in the manifest file.

    Example: With the above manifest, an activity declared as <activity android:name=".MainActivity"> is resolved to be com.example.myapp.MainActivity.

As such, the name in the package attribute should always match your project's base package name where you keep your activities and other app code. Of course, you can have sub-packages in your project, but then those files must import the class using the namespace from the package attribute, and any app components declared in the manifest must add the missing sub-package names (or use fully-qualified package names).

If you want to refactor your package name completely, be sure you update the package attribute as well. As long as you use Android Studio's tools to rename and refactor your packages, then these automatically stay in sync. (If they don't stay in sync, your app code can't resolve the R class because it's no longer in the same package, and the manifest won't identify your activities or other components.)

You must always specify the package attribute in your project's main AndroidManifest.xml file. If you have additional manifest files (such as for a product flavor or build type), be aware that the package name supplied by the highest-priority manifest file is always used in the final merged manifest. For more information, see Merge multiple manifest files.

One more thing to know: Although you may have a different name for the manifest package and the Gradle applicationId, the build tools copy the application ID into your app's final manifest file at the end of the build. So if you inspect your AndroidManifest.xml file after a build, don't be surprised that the package attribute has changed. The package attribute is where Google Play Store and the Android platform actually look to identify your app; so once the build has made use of the original value (to namespace the R class and resolve manifest class names), it discards that value and replaces it with the application ID.