How to change package in Android Studio

Changing the package name is one of the most common tasks in application development, be it changing a company's domain, rebranding, or simply fixing a mistake at the beginning of a project. For beginners, this process may seem confusing, as in Android Studio there are several concepts related to the name: applicationId, package name in the manifest and the physical folder structure in the project. Failure to understand the difference between these terms often leads to build errors or the inability to update the application on user devices.

In this article, we will look at all the nuances of the procedure so that you can safely rename your project. It is important to understand that simply renaming a folder in Explorer or ID will not update references within the code and configuration files. Android Studio provides tools for refactoring, but they must be used with caution so as not to break Gradle or R-class.

Before proceeding, it is strongly recommended that you back up the project or make a commit to version control. Any manipulation of package names affects many files at once, and the ability to rollback will become your insurance against fatal errors. Let's look at a step-by-step algorithm that will allow you to change application identifiers correctly.

The difference between ApplicationId and Package Name

The first step to a successful change will be a clear understanding of the terminology. In the Android ecosystem, these two concepts are often confused, although they serve different functions. Package name (package name) is used by the Java/Kotlin compiler to organize code and generate an R class that references resources. It is this name that is used to build class paths in the source code.

On the other hand, applicationId is a unique identifier for your application in the Google Play Store and on the user’s device. It is by this ID that the Android system determines whether the installed application is an update of a previous version or a completely new app. If you change the applicationId, the operating system will consider it a new application, and the old user's data will not be available.

⚠️ Attention: If your application is already published on Google Play, you cannot change applicationId . This will create a new listing and users will not receive the update. You can only change the internal structure of packages (package name), if required by the code.

In modern versions of Gradle, these values ​​are often separated. In the file build.gradle (app module level) you can see an explicit applicationId, which overrides the package name specified in the manifest. This gives you flexibility: you can reorganize the code by changing the package structure, but leave the identifier for the store unchanged.

Preparing the project for renaming

Before starting any manipulations, you need to make sure that the project is in a stable state. Close all emulators and disconnect physical devices to avoid rebuilding conflicts. It is also worth checking that there are no uncommitted changes in the project that could be lost if refactoring fails.

It is important to switch the project view in Android Studio to Project (rather than Android) to see the real file structure. In standard mode Android IDE hides some implementation details, which can be confusing when manually renaming folders. Make sure you have write permissions in the project directory.

If you are using third-party libraries or SDKs (for example, Firebase, Facebook SDK), check their documentation. Some services are hardwired to package name and require a configuration update in their control panels after changing the name. Ignoring this step will lead to authorization errors or crashes during startup.

Changing ApplicationId in Gradle

The easiest and safest way to change the application identifier for the system is to edit the assembly file. Open the file build.gradle (usually located along the path app/build.gradle). Find the block defaultConfig. Inside it there is a line applicationId.

android {
defaultConfig {
applicationId"com.newname.app"
minSdkVersion 21
targetSdkVersion 33
versionCode 1
versionName"1.0"
}
}

Change the value in quotes to the desired one. Please note that the format must be strictly followed: domain names in reverse order, separated by periods. After the change, click the Sync Now button in the top panel of the IDE. This action will update the project configuration, but will not affect the physical structure of the code folders.

It is worth noting that changing just this setting will not require code refactoring unless you plan to change the folder structure. However, if you want to align your folder structure with the new name, you will need to follow the additional steps outlined below.

Renaming a package through refactoring

To change the physical folder structure and namespace in the code, use the built-in refactoring tool. Do not manually rename folders via Explorer or the "Rename" context menu without using the Refactor function, as this will break references in the code. Find the folder with the current package name in the directory java or kotlin.

Click on the package folder with the right mouse button, select Refactor -> Rename (or click Shift+F6). In the window that appears, select the option Rename package, not Rename directory. This is a key point: renaming the directory will leave the package declarations in the code files old, which will cause compilation errors.

⚠️ Warning: When renaming packages containing classes with native methods (JNI) or classes registered in the Manifest via string literals (for example, in android:name), the refactoring may not work automatically for all links. Manual verification will be required.

After entering the new name, click Refactor. The IDE will prompt you to find all usages and perform a rename. Agree with the action. If the package has a nested structure (for example com.example.old), you may need to perform the procedure for each level of nesting separately or move the classes to a new root package manually if the automation fails.

Updating AndroidManifest and configuration files

After refactoring the code, you need to check the file AndroidManifest.xml. The attribute package at the manifest root now serves as the default namespace for relative component names. If you've changed your package structure, make sure this attribute matches the new reality unless you're using an explicit applicationId in Gradle.

Pay special attention to lines where class names are fully qualified names. For example, if you have Activityspecified in the manifest as com.old.name.MainActivity, and you did not refactor the file itself, but only the folder, the link may stop working. In modern versions of Android Studio, the package attribute in the manifest is often ignored in favor of applicationId from Gradle, but for code purity it is better to synchronize them.

Don't forget about the configuration files of third-party services. For example, the file google-services.json for Firebase contains a field package_name. If you changed the package, you need to download a new file from the Firebase console for the new package and replace the old one. Without this, push notifications and analytics will not work.

Working with Google Services and ProGuard

Integration with Google services is the most vulnerable point when changing a package. The file google-services.json is strictly tied to the package name. When you add a new package to a Firebase project (or when you rename an existing one in the console), you get a new config. Simply replacing the file is not enough: you need to make sure that in the Firebase console the project is configured to work with the new ID.

Also check the ProGuard or R8 rules files (usually proguard-rules.pro). If they have rules that store specific classes by their full name (for example -keep class com.old.package.Model { *; }), they will stop working or will be applied to the wrong classes. Update the classpaths to match the new structure.

If you are using Deep Links (links that open the application), check the settings in the manifest in the intent-filtersection. Although the link scheme may not change, the host or path sometimes depends on the application structure. Additionally, if you use App Links, you will need to re-verify the domain for the new applicationId via file assetlinks.json.

Cleaning and final assembly of the project

After making all changes, you must perform a complete cleanup of the project. In the menu, select Build -> Clean Project, and then Rebuild Project. This will remove any temporary build files that may have retained old package references. Errors that occur at this stage usually indicate missing references in the code or resources.

Be sure to remove the old version of the application from the test device or emulator before running the new one. Because applicationId could have changed (or even if only the key changed during the configuration process), the system may refuse to update the application over the old one due to a signature or identifier conflict. Command for complete uninstall via terminal: adb uninstall com.new.name.app.

Run the application and carefully check the logs in Logcat. Look for the words "FATAL EXCEPTION" or warnings about missing resources. Pay special attention to the moments of initializing libraries and loading resources. If the application starts and works stably, the process can be considered complete.