How to change Package Name in Android Studio correctly

Changing package name in an Android application is a task that every developer faces sooner or later, be it when rebranding a product, selling the source code, or simply because of an error in the name at the start of the project. This process affects not only the folder structure in the source code, but also the build configuration files, the application manifest, and even the settings in the Google Play Developer Console. Failure to do this correctly can cause the project to stop compiling and prevent existing users from receiving the update.

Unlike simply renaming a file, changing the package ID requires synchronizing multiple ecosystem components. Android Studio. You will have to work both with the graphical interface of the development environment and manually edit files build.gradle i AndroidManifest.xml. It is important to understand the difference between the physical location of files in a directory java and the logical application ID, which is used by the system to install and update it.

This article is an expert guide that will walk you through all the steps of secure renaming. We will look at the nuances of working with new versions Gradle, features of migration to AndroidX and critical points that beginners often miss, leading to the loss of the user database in the application store. Follow each step carefully to avoid fatal errors in your project structure.

Preparing the project and creating a backup copy

Before making any changes to the project structure, it is extremely important to create a full backup copy. The process of renaming a package is destructive in nature: if at any stage you make a mistake in the classpath or file name, the development environment may lose references to resources, and restoring the functionality of the project will become a difficult task. Use a version control system such as Gitto capture the current state of your code.

Make sure your project is fully in sync with Gradle and free of compilation errors before starting the procedure. If the project already has errors, after changing the package name there will be many more of them, and you will not be able to understand which of them were there initially and which appeared as a result of refactoring. Close all code tabs in Android Studioto avoid conflicts when moving files.

⚠️ Attention: If your application is already published in the Google Play Console, changing the application ID will cause it to be treated as a completely new product by the store. You will not be able to update existing users' installations, and all reviews, ratings and download statistics will be lost for the new package.

Also check your project's dependencies. Third-party libraries connected via implementationmay be strictly dependent on the package structure if you use forks or local modules. Make sure you understand which parts of the code are yours and which are external, so as not to violate their integrity when refactoring.

Differences between Package Name and Application ID

One ​​of the most common sources of confusion is not understanding the difference between the package name in the source code and the application ID. In the context of the Android ecosystem, these concepts are closely related, but technically perform different functions. Application ID is a unique identifier that is used by the Google Play store and the operating system to identify the application on the user's device. It is this ID that must be unique globally.

On the other hand, Package Name in the context of the source code structure (folders in a directory src/main/java) is used by the Java or Kotlin compiler to organize classes and name resolution. Although traditionally they are often the same, technically you could have a package structure com.example.utilswhile the Application ID would be com.mycompany.superapp. Changing the physical location of folders does not always change the application ID, and vice versa.

In modern versions of Android Studio Android Gradle plugin, the parameter applicationId is moved to a block defaultConfig of the assembly file. This gives developers flexibility: you can refactor the code, changing the package structure for maintainability, without affecting the ID under which the application is installed on users' phones. However, if your goal is to change the identifier to publish a new application, you need to change the field. applicationId.

Why does Google require a unique Application ID?

The Android system uses the Application ID as the primary key in the database of installed applications. If two applications have the same ID, the system considers them to be the same app. If you try to install a second application with the same ID, but a different signature, the installation will be blocked to prevent software substitution.

When planning changes, clearly define your goal: do you want to simply clean up the code (package refactoring) or create a new entity in the store (changing Application ID)? The further algorithm of actions depends on this answer.

Changing the Application ID in the build.gradle file

The first and most important step to change the application ID is to edit the build file. Open the file build.gradle (usually module app, path app/build.gradle or app/build.gradle.kts in new projects). Find the block android, inside it is the section defaultConfig. This is where the line that defines the unique identifier is located.

You need to change the value of the parameter applicationId. The syntax may differ depending on the build script language (Groovy or Kotlin DSL). Make sure that you change it applicationIdand not namespaceif they are separated in your version of the plugin. After making changes, be sure to click the Sync Nowbutton that appears at the top of the editor to have Gradle apply the new settings.

android {
defaultConfig {
applicationId"com.newname.myapplication"
minSdk 21
targetSdk 33
versionCode 1
versionName"1.0"
}
}

If your project uses flavor dimensions or different build variants, check to see if applicationId is not overridden within specific blocks productFlavors or buildTypes. In such cases, the identifier can be generated dynamically, for example, by adding a suffix to the base ID. Changing the base ID in defaultConfig will affect all build variants unless they have an explicit override.

After synchronization, Gradle will rebuild the project indexes. At this stage, the application itself has not yet been renamed in the code, but the build system already knows under what name it should be compiled and installed on the device.

Refactoring the package structure in Android Studio

Now that the build ID has been changed, it is necessary to match the physical structure of the source code. To do this in Android Studio a powerful refactoring tool is provided. Switch the project view to Android mode (drop-down list above the project tree on the left) to see the logical structure, or to Project mode to work with real file system folders.

Find the root folder of your current package in the java or kotlin. Right-click on it, select Refactor → Rename (or press the key Shift+F6). In the dialog box that appears, enter a new package name. The development environment will offer several options: rename only the directory or move the classes to a new package. Select the option Rename packageto change the package declaration in all files automatically.

If you want to change only part of the name (for example, replace com.oldname by com.newname), you may need to perform this operation step by step, starting from the deepest nesting level or, conversely, from the root, in depending on the IDE logic. Android Studio will automatically update the directives package at the beginning of each source code file and fix all imports (import) that reference moved classes.

Action	Where executed	Impact on code
Changing applicationId	build.gradle	Changes installation ID, does not affect imports
Refactor → Rename Package	Project tree (Java/Kotlin)	Changes folders, package directives and imports
Manual moving files	File system	High risk of errors, breaks imports

After refactoring is complete, carefully check files that are not part of the main source code, such as ProGuard configuration files or obfuscation rules. Paths to classes in files proguard-rules.pro are written manually and are not automatically updated by the refactoring tool.

Updating AndroidManifest and resources

File AndroidManifest.xml is the core of the application configuration. Although modern versions of Android Studio often update the attribute package in the tag <manifest> automatically when refactoring, it is always worth checking it manually. Make sure the attribute value matches the new package name or is left blank if you rely on applicationId from Gradle (this is the recommended approach in newer SDK versions).

Pay special attention to components that reference classes via string names. This applies to elements <activity>, <service>, <receiver> and <provider>. If you used fully qualified class names (for example, android:name="com.oldname.MainActivity"), they need to be updated. If a shorthand notation was used (for example, android:name=".MainActivity"), then the dot at the beginning indicates the relative path from the manifest package, and such links will be updated automatically when the manifest package changes.

Remember to check the resources, especially XML files, where Custom Views may be specified. In markup/layout files, full class names are also written as strings. The refactoring tool will usually find and update them, but searching the entire project (Ctrl+Shift+F) using the old package name will not hurt.

⚠️ Attention: If your application uses ContentProviders with authorities hard-coded in the code or manifest (for example, com.oldname.provider), they need to be updated manually. Otherwise, other applications or system components will not be able to access your application data after renaming.

Also check the settings in the file AndroidManifest.xmlrelated to permission limits and signature, if they were tied to the package name. In some cases, old analytics or advertising libraries require registration of a new package name in their personal accounts for tracking to work correctly.

Setting up Flavors and application signatures

In complex projects, they are often used product flavors to create different versions of the application (for example, free/pro, dev/stage/prod). Each taste can have its own applicationIdSuffix. When changing the package base name, ensure that the suffixes still map correctly to the new base name and do not create conflicts or invalid identifiers.

A critical point is the application's Signing Config. Keystore keys are tied to a specific Application ID. If you change the ID on an existing project that you plan to update in the store, you must continue to sign the new application with the same key as the old one, otherwise the update will not work. However, if this is a completely new application, you need to create a new key or use a debug key for tests.

Check the file build.gradle in section signingConfigs. Make sure that the keystore paths (storeFile) and passwords are correct. Signing error is one of the most common problems after refactoring, which appears only at the stage of building the release version (assembleRelease).

If you use Google Play App Signing, remember that the upload key (Upload Key) you can change in the console, but the App Signing Key, which is stored by Google, remains the same for the original application. For a new package name, the procedure starts from scratch.

Frequent errors and solutions to compilation problems

After all the changes, the project may not be built the first time. that there is an import of an old package somewhere in the code. Use the function Unresolved reference. This means that somewhere in the code there is still an import of the old package. Use the function Optimize Imports (Ctrl+Alt+O on Windows/Linux or Ctrl+Option+O on macOS) to automatically remove unused imports and correct classpaths.

Another common problem is with the Gradle cache and IDE. If you see strange errors that have no logical explanation (for example, the file exists, but the studio “does not see it”), try clearing the cache. Execute the command Invalidate Caches / Restart from the menu File. This will force Android Studio to rebuild all project indexes to reflect the new package names.

Also check the test files. Unit tests (src/test) and instrument tests (src/androidTest) are in separate source sets. Refactoring the main code does not always automatically update the tests, especially if they use hard string class references or reflection. Run the tests after renaming to make sure they work.

# Commands for cleaning and rebuilding in the terminal
./gradlew clean
./gradlew build

If you are using libraries that generate code (for example, Room, Dagger/Hilt, DataBinding), make sure that the generated classes are also updated. Sometimes you need to delete the folder build in the root of the project and in the module app manually to force the annotation processors to generate the code again with new package names.

What to do if Android Studio does not offer to rename the package?

This can happen if the structure folders does not match the declared package in the files, or if the folder is not marked as "Sources Root". Try switching the project view to "Project Files", find the folder manually, right-click → Refactor → Move. Also make sure that the package directive is correctly specified in the first line of the .java or .kt files.

Is it possible to change the package name of an already published application?

Technically, yes, but for the Google Play store it will be a new application. You will not be able to "upgrade" for users of the old version. You will have to publish it as a new product, and either delete the old application or maintain it in parallel, which divides your audience and ratings.

Does changing the package affect Firebase and other services?

Yes, it has a critical effect. In the Firebase console, the application is bound to Package Name / Application ID. After the change, you will need to add a new Android application to the Firebase project, download the new file google-services.json and replace the old one in the project. The old settings and database will remain tied to the old ID unless you migrate manually.

Do I need to change the application name (app_name) in strings.xml?

No, the name of the application that the user sees on the phone screen (app_name in strings.xml), has nothing to do with the technical package name. You can leave the name "My Calculator", even if the package is called com.company.utils.math. These are independent parameters.

How to change the package in a project to Flutter or React Native?

In cross-platform frameworks, the procedure is similar, but requires changing the platform configuration files: android/app/build.gradle and AndroidManifest.xml for Android, as well as Info.plist and schema settings in Xcode for iOS. In Flutter, you may also need to clean out the folder build and regenerate the files.