The development of a mobile product often begins with a working title, which, during the evolution of the project, ceases to correspond to its real essence or marketing strategy. Changing a name is not just a cosmetic change, but a serious procedural task that affects the architecture of the project. Many new developers are faced with the situation where they need to change the display name, but at the same time keep the internal structure unchanged, or vice versa - to carry out a complete refactoring.
In the environment Android Studio this process requires care, since the project management system tightly links package identifiers, resources and the application manifest. Errors at this stage can lead to the project not being built and version conflicts appearing on users' devices. It is important to understand the difference between what the application is called for the user in the launcher, and how it is identified by the Android system through a unique package name.
This instruction covers all aspects of renaming: from a simple change of title in the interface to a deep reorganization of source code directories. We'll look at built-in IDE tools, manual editing of configuration files, and important nuances that are often overlooked when migrating projects.
The difference between display name and package ID
Before making changes to the code, it is necessary to clearly distinguish between two concepts that are often confused by newbies. The first is application name, that is, the text that the user sees under the icon on the desktop of his smartphone. The second is application ID or package name, which acts as a unique digital fingerprint of the app in the Google Play ecosystem and in the device’s file system.
Changing the display name is a safe and reversible procedure. You can change it as many times as you like without affecting the installation of updates. The user will simply see a new sign, but the system will continue to perceive the app as the same product. This is regulated solely by string resources in the file strings.xml.
The situation changes dramatically when it comes to changing the package identifier. If you change application ID from com.example.oldapp to com.example.newapp, the operating system will consider it a completely new, independent application.
⚠️ Warning: Changing the package name will prevent users who installed the old version from receiving the update. For them, this will be installing a new application from scratch, and all the data from the old version will remain isolated.
Therefore, changing the identifier should be resorted to only in extreme cases, for example, when selling a project or a complete rebranding with a clean slate start.
The table below compares the consequences of changing these parameters:
| Parameter | Where changes | Impact on updates | Impact on data |
|---|---|---|---|
| Display name | res/values/strings.xml |
None | Missing |
| Package Name | build.gradle and folder structure |
Blocks update | Requires transfer or reset |
| Process name | AndroidManifest.xml |
May cause crash | No impact |
If you plan to publish your application on Google Play, remember: after the first publication, you cannot change the package name. Choose it with the utmost care at the start of the project.
Changing the display name of an application
The simplest and most common scenario is the need to change the name that the end user sees. This operation does not require restructuring the project structure and is performed by editing resources. In Android, all string literals are placed in separate files for ease of localization and management.
You need to go to the directory app/src/main/res/values and open the file strings.xml. Inside the tag <resources> find a line with the name app_name. It is the value of this tag that is pulled into the manifest and displayed in the launcher. Replace the old value with the new one, respecting the XML syntax.
Sometimes the application name is hardcoded directly into AndroidManifest.xml, which is a bad practice, but can be found in legacy projects. In this case, find the attribute android:label in the tag <application>. If there is a direct value in quotes, replace it with a link to a resource, for example @string/app_nameto manage the name centrally.
⚠️ Attention: After changing the name, be sure to run the commandClean Projectand thenRebuild Project. The Android Studio build cache sometimes retains old metadata, and changes may not be reflected immediately on the emulator.
Be sure to check how the new name looks in different languages if your project supports multilinguals. Files strings.xml can be duplicated in folders with locale suffixes, for example values-es for Spanish or values-de for German. Updating only the main file will leave users with different language settings with the old name.
Complete change of Package Name and package structure
If your task requires changing the unique identifier, the process becomes much more complicated. Android Studio provides built-in refactoring that automatically updates file paths and imports in your code, but it requires proper sequencing. You should start by changing the assembly configuration.
Open the file build.gradle (app module level) and find the block defaultConfig. The parameter applicationId must be changed to the new desired identifier. It is this value that tells the compiler and the app store who is the owner of this APK file. Do not confuse it with the parameter namespace, which in new versions of Gradle can be included in the plugin settings or manifest.
After changing the gradle file, go to the project window, selecting view Android. Find the folder with the current package name (for example, com.example.oldname). Right-click on it, select Refactor → Rename. In the dialog box that appears, select the option Rename packagerather than Rename directory. This is a critical point: renaming the directory will not update the declarations package in the headers of Java or Kotlin files, which will lead to compilation errors.
Enter the new package name and confirm the action. The IDE will prompt you to run Do Refactor. The system will automatically go through all source code files, update instructions package and correct all imports of classes that referenced old paths.
What to do if the refactoring did not work?
Sometimes the built-in tool skips files that were created manually or that are outside the standard source sets. In this case, you will have to manually check all the files in the src directory and replace the old package name in the first line of each file.
☑️ Checklist for changing a package
Manual editing of AndroidManifest.xml
Despite the power of automatic tools, the manifest file often requires manual review and adjustment. This is the central configuration node where all application components are described. After changing the package, ensure that the attribute in the root tag matches the new name, if explicitly specified. Pay special attention to components that use fully qualified class names in attributes. Although relative paths (starting with a dot) usually resolve correctly relative to the new package, explicitly specifying old paths can cause package in the root tag <manifest> matches the new name if explicitly specified.
Pay special attention to components that use fully qualified class names in attributes android:name. Although relative paths (starting with a dot) usually resolve correctly relative to the new package, explicitly specifying old paths can cause ClassNotFoundException at startup. Also check the <provider>section, especially if you use FileProvider to work with files.
The android:authorities attribute of providers often contains a strict binding to the package name. If you changed the package but left the old authority in the manifest, the application may crash when trying to open a file or take a photo through the camera of a third-party application.
⚠️ Attention: When using Firebase, Google Maps or other SDKs, check their configuration. Often in the consoles of these services, the binding goes to a specific package name, and changing the identifier will require registering a new project in the corresponding service.
For complex cases when automatic refactoring cannot cope with paths in the manifest, you can use a search throughout the entire project (Ctrl+Shift+F). Enter the old package name and carefully review all occurrences in the XML files, replacing them with the new ones. Be careful not to replace the names of libraries or third-party classes that accidentally match part of your name.
Updating Gradle configuration and dependencies
The Gradle build system stores many references to the project structure. Besides applicationId, it's worth checking the signing config settings if you use different keys for debugging and release. Sometimes the paths to the key store (keystore) are written with relative paths, which can be broken when moving the project root folder during refactoring.
The file build.gradle may also contain dependencies that reference local modules or libraries if your project has a modular structure. Make sure all internal module references are up to date. If you use Dynamic Feature Modules, their manifests also require updating the package name and base module dependencies.
After all changes to the configuration files, you need to synchronize the project with the Gradle files. Click the Sync Nowbutton that appears at the top of the editor. If synchronization was successful, try building the debug version.
Successfully building the project after changing the package is only half the battle. Be sure to test installing the APK on a clean device that has not previously installed an application with the old name.
Pay attention to the build scripts if you are using proguard-rules.pro or keep.rules. Obfuscation rules can contain hard references to package and class names. If there are rules like -keep class com.old.package.**, they need to be updated, otherwise after enabling minification for the release build, the application will stop working.
Checking work after renaming
The final stage is comprehensive testing. First, remove the old version of the application from the emulator or test device. This is necessary to avoid conflicting signatures or residual data. Install the freshly compiled APK and make sure that the icon is displayed with the new name.
Launch the application and check the basic functionality. Pay special attention to features related to Deep Links, notifications, and working with the file system. Often this is where errors appear related to incorrectly updated paths or provider authorities. Check the logs through Logcat for errors PackageManager.
If the application uses a SQLite or SharedPreferencesdatabase, remember that when you change the package name, the path to storing the data will change.
/data/data/com.new.package/ will be a new directory. The old data will remain in the folder with the old name and will not be accessible to the new application. This is the behavior of the Android security system, and it is impossible to bypass it using standard means without root access.
For a full test, it is recommended to build a signed release bundle (AAB) and upload it to internal testing of Google Play Console (if you have access). Only the store environment can definitively confirm that all metadata, signatures and identifiers are correct and do not conflict with existing records.
Is it possible to change the package name of an already published application on Google Play?
No, technically this is not possible. Google Play identifies the application precisely by its package name. To change it, you will have to create a new application in the developer console with a new identifier, transfer the rating and reviews there (which is also impossible automatically) and ask users to install the new version manually by deleting the old one.
What to do if Android Studio does not see classes after renaming?
Try running the command File → Invalidate Caches / Restart. Sometimes project indexing gets lost when massively renaming files. If this does not help, check that in the .java or .kt files in the first line the package statement corresponds to the actual folder structure.
Does renaming affect the operation of Firebase Analytics?
Yes, it does. In the Firebase console, the project is associated with a specific application ID. When you change the identifier in the application, the data will no longer flow into the old Firebase project. You will need to add a new application to the Firebase console, download the new file google-services.json and replace the old one in the project.
How to rename only the project folder in Explorer without changing the code?
You can rename the project root folder in the operating system. However, after opening in Android Studio, you will need to update the paths in the file settings.gradle (include line) and possibly in local.propertiesif it contains absolute paths to the SDK or other tools. There is no need to change the application code.
Is it necessary to change the package name when changing the company domain?
No, it is not necessary. Package name is a technical identifier. If your site domain has changed, but you do not plan to create a new application from scratch, it is better to keep the old package name to support existing users. The display name and icon can be changed without problems.