How to Change Your Android App's Package Name (The Right Way)

How to Change Your Android App's Package Name Correctly

Changing your Android app's package name is a common task, but doing it incorrectly can break your build, disrupt services like Firebase, or even create a new app on the Play Store. This guide will walk you through the safe way to refactor your package name and explain the critical nuances.

The Two Types of "Package Name"

It's crucial to understand the difference between two concepts:

1. The Code Package Name: Defined in your AndroidManifest.xml, this is the root package for your source code and R classes.

2. The Application ID: Defined in your build.gradle file, this is the unique identifier for your app on the Google Play Store and for services like Firebase and AdMob.

You can change the first without changing the second.

Step-by-Step: How to Refactor Your Package Name

Follow these steps inside Android Studio to rename your code package safely.

1. Update the AndroidManifest.xml

Open your AndroidManifest.xml file and locate the package attribute. Change it to your new package name.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.mas.appname">
    ...
</manifest>

2. Use the Refactor Tool (Do Not Rename Manually!)

Manually renaming folders is error-prone. Always use Android Studio's built-in tool.

1. In the Project view (set to Android or Project), right-click on the package you want to rename (e.g., com.atif.appname).

2. Select Refactor > Rename....

3. Choose "Rename Package".

4. Enter the new package name (e.g., com.mas.appname).

5. Click Refactor. This will automatically update references throughout your code.

3. Update the applicationId in build.gradle (If Desired)

Open your module-level app/build.gradle file. If you want your app's unique ID to change, update the applicationId. Warning: This has major consequences (see below).

android {
    defaultConfig {
        applicationId "com.mas.appname" // Change this if you want a new app ID
        ...
    }
}

4. Clean and Rebuild

After refactoring, always clean and rebuild your project to ensure everything is correctly generated.

1. Go to Build > Clean Project

2. Then, Build > Rebuild Project

5. Check for Hardcoded References

While the refactor tool is excellent, double-check for any hardcoded strings that might reference the old package name, such as in Intent filters or custom logic.

⚠️ Critical Warning: Firebase, AdMob, and the Play Store

This is the most important part. Changing your applicationId has significant effects:

• Google Play Store: Changing the applicationId creates a brand new app. Users of your old app will not receive an update; it will be a separate listing.

• Firebase & AdMob: These services tie your configuration to a specific applicationId. You cannot change the package name for an existing Firebase or AdMob app.

What Are Your Options?

Option 1: Refactor Code Only (Recommended for Existing Apps)

• Keep the original applicationId in your build.gradle file (e.g., com.atif.appname).

• Only refactor the code package name (e.g., to com.mas.appname).

• Pros: Your app remains the same on the Play Store. Firebase, AdMob, and all services continue to work without any reconfiguration. This is perfectly safe for updating an existing app.

Option 2: Change the applicationId (For a Truly New App)

• Change the applicationId in build.gradle to the new name.

• You must:

  1. Create a new app in the Firebase console with the new package name and download a new google-services.json file.

  2. Create a new app in AdMob and update all ad unit IDs in your code.

  3. Upload it as a new application on the Google Play Console.

Conclusion

To summarize:

• Use the Refactor > Rename tool to change your code structure.

• If you are updating an existing app on the Play Store, do not change the applicationId in your build.gradle file.

• Only change the applicationId if you are intentionally creating a new, separate app identity.