Development of applications for the platform Android often requires changes to the project structure at the earliest stages. One of the most common tasks when initializing a new project or inheriting someone else's code is changing the application ID. Many new developers find it difficult to figure out how to change the package name in Android Studio without breaking the code. This is not just renaming a folder, but a complex process that affects configuration files and links in the source code.
If this procedure is not performed correctly, the application may no longer build, or the build system will generate errors related to missing classes. It is important to understand the difference between the physical location of files in directories and the logical name of the package, which is written in the file build.gradle. In this article, we will analyze in detail a safe algorithm of actions that will allow you to refactor the project without loss of functionality and with minimal risks.
Before proceeding with technical manipulations, you need to create a backup copy of the project or record the current state in the version control system Git. This is a critical step because automated refactoring tools can sometimes behave unpredictably when dealing with complex dependency structures. If something goes wrong, you can always roll back to the working version in a matter of seconds.
Preparing a project for structure changes
The first step before any global change in the project structure is to carefully check the current settings. Open your project in the development environment Android Studio and make sure that all files are synchronized. Often errors occur because Gradle did not have time to complete background indexing processes. Wait until all the loading indicators in the bottom panel of the interface disappear.
You should also check if the project has any hard links to the old package name in resources or native code. If your application uses JNI or NDK C++, changing the package will require manually updating the corresponding header files and build scripts. In purely Java or Kotlin projects, this risk is minimal, but you should not lose vigilance.
⚠️ Attention: Before starting work, make sure that you have closed all emulators and disabled physical devices running the old version of the application. This will prevent conflicts when installing an updated version with a new ID.
It is also recommended to clear the build cache to avoid using outdated artifacts. To do this, you can use the menu Build → Clean Project, and then Build → Rebuild Project. This action will take some time, but will ensure the purity of the experiment. Only after successfully building the current state can you proceed to the next stage.
Use the keyboard shortcut Ctrl+Alt+Shift+S to quickly access the Project Structure settings, where you can preview the modules.
The main method is through the Refactor tool
The most reliable and preferred way to change the name is to use built-in refactoring tool. This method automatically updates links in all project files, minimizing human error. Find the folder in the project window that matches your current package. It is usually located along the path app → java → com.example.oldname.
Right-click on the folder with the name of the package you want to change. In the context menu, select Refactor → Rename. A dialog box will open where the system will prompt you to enter a new name. It is important to be careful here: you can change only the last part of the path or rename the entire domain structure.
If you decide to change all nesting levels (for example, from com.example.app to org.mycompany.newapp), the tool will offer to break the process into several steps. Agree with this, as this will allow you to control every change. After entering a new name, click the Refactorbutton. The system will scan the entire project and offer (Preview) changes before applying them.
- 🔍 Automatic update of imports in all Java and Kotlin files.
- 📂 Physical movement of files to new directories according to the package structure.
- 🔄 Updating links in markup files (XML) and resources.
- ⚙️ Adjusting manifest configuration files.
After confirming the actions, Android Studio will move the files. In the Event Log you will see a report of completed operations. If there are name conflicts or ambiguous references in the process, the IDE will highlight them in red and require manual intervention. Carefully study these places before continuing.
Manually editing the Build Gradle file
Even after successful refactoring through the menu, it is critical to check the build configuration file. The package name, which is used to identify the application on Google Play and on the device, is stored in the property applicationId. Find the file build.gradle (Module: app) in the root of your application module.
Inside the block android { defaultConfig {... } } locate line applicationId. The value of this parameter must exactly match the new name of your package. If the refactoring tool does not update this field automatically (which happens in older versions of the IDE), you will have to do it manually. An error here will result in the application being considered completely different from the previous version.
android {
defaultConfig {
applicationId"com.newname.myapp"
minSdkVersion 21
targetSdkVersion 33
versionCode 1
versionName"1.0"
}
}
It is also worth paying attention to the property namespace, which appeared in more modern versions of the Android Gradle plugin. It often duplicates applicationId, but serves to generate a class R. Make sure both values are in sync and match the new directory structure. Out of sync with these parameters will cause compilation errors like "Package does not exist".
⚠️ Attention: The value
applicationIdis a unique identifier for your application in the store. If you change it, you will not be able to update a previously published application under the old name. This will be considered a new product.
☑️ Check the Gradle configuration
Updating AndroidManifest.xml
The manifest file is the passport of your application, and it should also reflect current changes. Open the file AndroidManifest.xmllocated in the folder app → manifests. The topmost tag <manifest> there is an attribute package. In modern versions of Android Studio, this attribute may be hidden or replaced by a namespace declaration in Gradle, but it is still worth checking.
If the attribute package is explicitly specified in the XML, it must match the new package name. In addition, check all application components: Activity, Service, Receiver. Make sure that attributes android:name do not use fully qualified class names with the old package prefix. If a shorthand notation is used (for example, .MainActivity), then it will be resolved correctly relative to the new package.
Pay special attention to Intent Filters and Permissions if they are specific to your domain. Sometimes developers hardcode package names in the metadata for integration with third-party SDKs (like Firebase or Maps). Such strings are not updated automatically and require manual search and replacement through the combination Ctrl+Shift+R.
| Configuration element | Where is located | What to check | Criticality |
|---|---|---|---|
| Application ID | build.gradle | Match with new package | High |
| Package Name | AndroidManifest.xml | Package attribute in the manifest tag | Medium |
| Namespace | build.gradle / Manifest | R class generation | High |
| Imports | Java/Kotlin files | No broken links | High |
Working with resources and string constants
Changing the package name often entails the need to update string resources, especially if the name of the application or domain is hard-coded in the interface. Check the file strings.xml for any mention of an old email address, website, or ID.
It's also worth checking the configuration files for third-party libraries. Many SDKs require you to specify the package name in its settings within the project or in the developer console of the corresponding service. For example, when changing a package, you will need to create a new application in the console Firebase and download the updated file google-services.json.
Replacing applicationId entails the need to re-register the application in all external services (Push notifications, analytics, maps), since they are tied to this identifier. Do not forget to update the signature hashes (SHA-1, SHA-256) in the corresponding developer accounts, since when changing a package, the debug signature may also change.
Why do signature hashes change?
The signature hash is calculated based on the certificate and package name. When you change the package, the input data for generating the application identifier in third-party services changes, so the old keys become invalid.
Cleaning and final assembly of the project
After making all changes, you must perform a complete cleanup of the project. The compiler cache may store references to old classpaths, which will lead to strange errors at runtime. Run the command File → Invalidate Caches / Restart and select the option to clear the cache. This will restart Android Studio and rebuild the indexes from scratch.
After restarting the IDE, try building the project (Build → Make Project). If the build was successful, connect the device or launch the emulator. Try installing the application. If a version with an old package name was already installed on the device, the system will offer to install the application as a new one, since the identifiers do not match.
Test the main functions of the application: launch, navigation, working with the network and databases. Make sure there are no ClassNotFoundException or NoClassDefFoundErrorerrors, which often indicate missing references in the code or manifest. Only after successfully passing the tests can the procedure be considered completed.
⚠️ Attention: The Android Studio interface and file structure may vary slightly depending on the IDE version and the version of the Android Gradle plugin. Always check the official documentation when working with new versions of tools.
Successful package change is confirmed only by a clean build of the project and successful launch of the application on a real device without errors in Logcat.
Frequently asked questions (FAQ)
Is it possible to change the package name of an already published application in Google Play?
Technically, it is possible to change applicationId but for the Google Play store this will mean creating a completely new application. You won't be able to update an existing app in the store by simply changing the package. You will have to publish it as a new product, and all users of the old version will not automatically receive the update.
What to do if the R class disappears after refactoring?
The class R is generated automatically based on resources. If it is not visible, check for errors in the XML resource files (unclosed tags, invalid names). Also make sure that the namespace v build.gradle property is specified correctly. Try doing Build → Rebuild Project.
How to change the package name if the project is written in Kotlin?
The process is absolutely identical to the project in Java. The refactoring tool in Android Studio handles both languages equally well. The only difference may be in the syntax of imports, which will be updated automatically.
Do I need to change the package name when forking an open project?
Yes, this is a mandatory practice. If you plan to modify someone else's project and publish it, you must change applicationIdto avoid conflicts with the original application for users and violations of application store rules.
Does changing the package affect the operation of Firebase Crashlytics?
Yes, it does. You will need to add a new app to the Firebase console with a new package name, download the updated config and replace the old file in the project. Old crash data will remain tied to the old identifier.