Developing mobile applications often requires changing the internal structure of the project, especially when it comes to identifying the application in the Android system. Changing the package name is a critical operation that allows you to update the unique identifier applicationIdused by app stores such as Google Play. Errors at this stage can lead to the inability to install updates or conflicts with already released versions of the product.
Many developers, especially beginners, confuse the concept of the package name in the source code structure and the application identifier in the assembly. It is important to understand that refactoring directories in Java or Kotlin do not always automatically change build settings. Improper execution of the procedure can break dependencies, resources, and even the process of compiling the project in the environment Android Studio.
In this material we will analyze in detail a safe algorithm of actions that will allow you to change the package name without losing functionality. We'll cover both built-in IDE tools and manual editing of configuration files so you can choose the most appropriate method for your situation.
Differences between Package Name and Application ID
Before starting any manipulations, it is necessary to clearly distinguish between two concepts that are often used as synonyms, but have different technical natures. The package name in the source code structure (Java/Kotlin package) determines the organization of classes within the project. It is a logical grouping of files that helps the compiler resolve name conflicts and organize the namespace.
On the other hand, Application ID is a unique identifier that the Android system uses to recognize your application on the user's device. It is this parameter that is indicated in the file build.gradle and it is the one that is displayed in the Google Play Console. If you want to release the application as a completely new product or clone, you need to change the Application ID.
In modern versions of Android Studio, these concepts are separated, which gives flexibility. You can leave the code package structure the same (for example, com.example.myapp), but change the assembly ID to com.newcompany.superapp. However, most often developers strive to synchronize them to maintain order in the project.
- 📦 Package Name: Defines the location of classes in directories
src/main/java. - 🆔 Application ID: A unique name for installing the application on the device and publishing it in the store.
- ⚙️ Manifest Placeholder: A variable that links the code and the build configuration.
⚠️ Attention: Changing the Application ID will make the new application completely separate from the old one for the Android operating system. Users will not be able to update the old version with a new one, since the system will consider them different apps.
Why does Google Play require uniqueness?
App stores use the Application ID as the primary key in the database. If you try to upload an APK with an ID that is already occupied by another developer or your old project with a different signing key, the upload will be rejected with a conflict error.
Preparing a project for refactoring
Before making changes to the project structure, it is strongly recommended to create a backup copy or commit the current state to a version control system such as Git. Refactoring packages is an operation that affects many files at once, and if an error occurs, rolling back changes without a restore point can be difficult.
Make sure your project is in sync with Gradle and does not contain compilation errors. Any existing problems may be exacerbated by changing package names, making it difficult to determine whether the error was caused by the changes or pre-existing. Close all open editor files so that Android Studio can correctly reindex the project after changes.
It is also worth checking for tight bindings to the package name in the code. Sometimes developers use the fully qualified class or package name in string literals, analytics settings, or when initializing third-party SDKs. Searching the project line for the current package will help identify such places in advance.
☑️ Preparing to change the package
Changing Application ID in Gradle
The most correct and modern way to change the application ID is to edit the assembly configuration file. Open the file build.gradle (module level, usually app/build.gradle) and find the block defaultConfig. This is where the parameter is located applicationId.
Change the value of this parameter to the desired new name. Syntactically, this looks like a quoted string. After making changes, you need to click the Sync Nowbutton that appears at the top of the editor for Gradle to apply the new settings. This action will update the project's metadata, but will not rename the physical source directories.
android {
defaultConfig {
applicationId "com.newname.projectname"
minSdkVersion 21
targetSdkVersion 33
versionCode 1
versionName "1.0"
}
}
It is important to note that changing this setting alone is enough for the compiled application to have a new identifier. However, if you want the folder structure to match the new name (which is good practice), an additional code refactoring step is required, described in the next section.
Use suffixes for different versions of the application. For example, set the applicationId "com.example.app.free" for the free version and "com.example.app.pro" for the paid version, using different flavors in Gradle.
Refactoring the package structure in the source code
If your goal is to change not only the build ID, but also the physical location of the source code files to match the new domain, use the built-in Android Studio refactoring tool. Never rename folders manually through the operating system explorer - this is guaranteed to lead to compilation errors.
First, switch the project view in the window Project to Androidmode. Find the root folder of your current package (usually located inside java or kotlin). Right-click on it, select Refactor, and then Rename. In the dialog box that appears, enter a new package name.
IDE will offer several options. Select Rename Packageif you want to change only the logical name, or Rename Directoryif you want to move the files to a new physical folder structure. It is generally recommended to select the option that moves files, as this ensures that the structure is fully consistent with the project.
| Action | Impact on code | Impact on assembly |
|---|---|---|
| Change applicationId | No changes to files | ID of installed APK changes |
| Rename Package (Refactor) | Updates import and directory | Requires manual editing of Gradle |
| Manually moving folders | Breaks paths and imports | Causes compilation errors |
After the refactoring is complete, Android Studio will automatically update all statements import in your classes. However, always check the file AndroidManifest.xmlas the package The manifest root may not have updated automatically in some versions of the IDE.
Android Studio's refactoring tool automatically updates all class references and imports, making it the only safe way to change the package structure.
Updating AndroidManifest and resources
File AndroidManifest.xml is the central node of the application configuration. The attribute package in the opening tag <manifest> must match the package name of your source code, unless you use ID/code package separation. Make sure this value is up to date.
Also, check application components such as Activity, Service and Receiver. If they are declared with a fully qualified class name (beginning with a dot), the system will automatically substitute the current package. However, if the names are spelled out in full (for example, com.old.name.MainActivity), they must be updated manually or through class refactoring.
Remember to check the resources. In layout files (XML layouts) or in string resources, there may be references to classes through type attributes android:name in fragments. Although modern tools try to track such relationships, manual checking will not be superfluous.
⚠️ Attention: If you use libraries that require registration in the manifest with the full package name (some analytics or advertising SDKs), their settings will also require manual updating after changing the name.
Cache clearing and final assembly
After making all changes to the configuration and file structure, you need to perform a deep cleanup of the project. Gradle and Android Studio actively cache file paths and build metadata. The old cache may contain references to directories that no longer exist, which will lead to strange compilation errors.
In the top menu, select Build, then Clean Project. After cleaning is complete, run Rebuild Project. This process will force the IDE to re-index all files and build the application from scratch using the new paths and IDs.
If the build process encounters "Package does not exist" or "Cannot resolve symbol" errors, check to see if there are any old imports in files that were not affected by the automatic refactoring. Sometimes it is also useful to select File -> Invalidate Caches / Restartto completely reset the internal state of the IDE.
# Commands for clearing via the terminal (if building via CLI)
./gradlew clean
./gradlew build
Successfully building the project without errors is the final confirmation that the package name has been changed correctly. You can now run the app on your emulator or device and make sure it installs with the new package name.
Before publishing the updated version to the store, be sure to check that the new Application ID does not conflict with your other applications in the developer console.
Frequently asked questions
Is it possible to change the package name already published application on Google Play?
No, it is impossible to change Application ID for an already published application. Google Play considers an application with a new ID as a completely new product. You will have to create a new application in the developer console; ratings and reviews cannot be transferred. The old application can be deleted, but its ID will remain reserved.
What if Android Studio does not offer the Rename Package option?
Make sure that view is selected in the project window Androidand not Project. If you are in file view mode (Project), the option to rename a package may not be available or may not work correctly. Also check if the file you are trying to rename is opened in read-only mode.
Does changing the package affect the operation of Firebase or other services?
Yes, it does. Services like Firebase are tied to a specific Application ID. After changing the ID, you will need to add a new application to the Firebase console, download the updated configuration file (google-services.json) and replace the old one in the project with it.
How to change the package name in a Kotlin Multiplatform project?
In KMP projects, the procedure is similar, but requires attention to common modules. Change the package in the module shared or common, and make sure that the settings in build.gradle.kts for all targets (Android, iOS) are consistent. For iOS, the package affects the class prefix in the generated framework.