How to correctly change Package in Android Studio

Developing applications for a platform Android often begins with choosing an architecture and naming components. However, in the early stages or when refactoring existing code, developers often need to change the root package of the project. This procedure, while seemingly trivial at first glance, actually requires attention to detail as it involves many configuration files. Failure to complete the steps correctly can result in the application not building or, worse, launching but not being able to find its resources.

Many beginners make the mistake of simply trying to rename folders in the operating system explorer or manually editing files without using the built-in tools of the development environment. This approach is extremely risky and can break connections between classes, especially if the project uses navigation systems, dependencies through build.gradle or specific proguard settings. In this article, we will analyze in detail a safe algorithm of actions that will allow you to change Package Name without losing the functionality of your product.

The process of changing a package includes not only renaming directories, but also updating the manifest, build scripts, as well as checking imports in the code. We will look at the main stages, typical errors and how to eliminate them. It's important to understand the difference between the physical location of packages on the file system and the logical application ID that is used to install it on the device. Both of these aspects require synchronous changes for the environment to work correctly Android Studio.

Preparing the project for refactoring

Before making any changes, it is critical to create a backup copy of your project. Even with reliable refactoring tools, there is always a risk of human error or IDE failure. Saving a working version will allow you to quickly roll back if unexpected problems arise with your build or application logic.

Make sure your project is in sync with a version control system such as Git. This will give you the opportunity to see all the changes made to the files and, if necessary, undo them individually. It is also recommended to close any open code editor files so that the development environment can properly index the project before making major changes. If you have dozens of files open, the refactoring process may take longer or may not proceed correctly.

⚠️ Attention: Before you begin, make sure that you do not have uncommitted changes in the local repository that you are not willing to lose. Refactoring a package changes the file structure, which can create merge conflicts if you are working in a team.

Check the current project structure in display mode Projectrather than Android. This will allow you to see the real hierarchy of folders on the disk, rather than a virtual representation that often hides the nesting of packages. Understanding the physical structure is necessary to correctly perform the subsequent steps of renaming directories.

Changing the Application ID in Gradle

The first logical step is to change the unique application identifier. It is this parameter that tells the operating system and the store Google Playthat your application is a unique product. Changing this value will not automatically rename the folders, but will prepare the build system for the new conditions.

Open the file build.gradle (usually a module app) in text view mode. Find the block defaultConfig and parameter applicationId. Replace the old value with the new one, following domain naming rules (for example, com.newcompany.myapp). This action will update the identifier under which the application will be installed on devices.

It is important not to confuse applicationId with packageName in the manifest, although in modern versions Android Studio they are often synchronized. Application ID used exclusively for assembly and publishing, while the package name in the code defines the namespace for the Java or Kotlin classes. After making changes, be sure to click the Sync Nowbutton for Gradle to apply the new settings.

After synchronization, check if there are any errors in the window Build. Sometimes old dependencies may reference a previous package name, which will trigger warnings. In this case, you will need to manually adjust the paths in the configuration files of third-party libraries.

Refactoring the package structure through the IDE

The safest way to rename physical folders is to use the built-in refactoring tool Android Studio. Manually renaming folders in Windows or macOS Explorer will not update the references in the code, resulting in many compilation errors. The tool Rename will automatically update all imports and class references in the entire project.

Switch the project view to Projectmode. Expand the directory tree to the level where your current package is located (for example app/src/main/java/com/oldname). Right-click on the folder with the name of the old package and select Refactor → Rename. In the dialog box that appears, enter the new package name.

The development environment will offer several refactoring options. Select the option Rename packageif you want to change only the name of the current nesting level, or Rename directoryif you want to rebuild the entire path structure. To completely change the domain (for example, from com.example to com.newdomain), you may need to perform this procedure sequentially for each nesting level.

After confirming the operation Android Studio will begin analyzing all project files. This process may take some time depending on the size of the codebase. Once complete, all files will be moved to new directories, and the statements import at the beginning of each file will be updated accordingly.

Updating AndroidManifest.xml

The manifest file is the central hub of the application's configuration. Even if you changed the package name through refactoring, the attribute package on the root element <manifest> may require manual checking or updating, especially if you changed the structure manually or used complex naming schemes.

Open the file AndroidManifest.xml and make sure that the attribute package corresponds to the new name of your package. This attribute serves as the default namespace for all application components that do not have a full path specified in their attributes android:name. If the old name remains here, the components may not be found at startup.

Attribute	Location	Purpose	Impact on assembly
applicationId	build.gradle	Unique ID for installations	Critical
package	AndroidManifest.xml	Java/Kotlin namespace	Critical
directory	File system	Physical storage of classes	Critical
namespace	build.gradle (new)	Replaces package in the manifest	High

In the latest versions of Gradle Plugin attribute package in the manifest can be replaced with a property namespace in the file build.gradle. If you are using modern tools, check for the presence of the property namespace in the block android. If it is specified, then the value of the attribute package in the manifest can be ignored or used only as a fallback.

⚠️ Attention: If you use libraries that generate code (for example, Dagger, Room or Navigation Component), after changing the package, be sure to completely rebuild the project (Clean Project i Rebuild Project). Cached generation files may reference old paths.

Working with resources and R-class

One ​​of the most common problems after changing a package is class-related errors R. This class is generated automatically and contains links to all application resources (layout, strings, drawable). If the resource and code bundles are out of sync, the compiler will not be able to find the resource IDs.

Check the layout files (.xml in the folder layout). The root elements of some layout files may contain an attribute tools:context, which contains the full path to the activity. If this path is outdated, the layout designer Android Studio may not display the preview correctly, although this usually does not affect the build.

Also pay attention to resource files where fully qualified class names are used, for example, in custom views or styles. If you have written classes directly in XML (for example <com.oldname.CustomView />), you need to update them manually, since the refactoring tool does not always affect string values ​​inside XML attributes.

Why is the R class not found?

The R class is generated in the package specified in the manifest or namespace. If you renamed the code folders but forgot to update the manifest, the code will look for R in the old package and it will be generated in the new one. Solution: synchronize the package in the manifest and the folder structure.

To fix problems with R often it is enough to run the command Invalidate Caches / Restart. This will clear the IDE's internal indexes and force it to rescan all files again, correctly associating new package paths with resources.

Checking dependencies and third-party libraries

Modern applications rarely exist in a vacuum and often use many third-party libraries. Some of them may be tightly coupled to your application's package structure, especially if you use Dependency Injection or code generation mechanisms.

Carefully examine the configuration files of libraries such as Realm, Firebase or Retrofit. In some cases, paths to data models or services are written in strings. For example, the configuration ProGuard or R8 may have rules that explicitly specify old package names to preserve or obfuscation.

If you use Deep Links (deep links), check the settings in the manifest and in the developer console of the corresponding service. Links of the form myapp://profile can depend on the schema, which is sometimes associated with the package name. Changing the package may require updating the settings in Firebase Dynamic Links or App Links.

⚠️ Attention: Interfaces and rules for working with Deep Links may change on the part of the operating system or intermediary services. Always check the latest requirements in the official documentation of the service you use for navigation.

Don't forget to check the tests. Unit and instrument tests often contain hard references to application classes. After refactoring, test packages may also require updating if they were organized mirroring the structure of the main code.

Frequently asked questions (FAQ)

Is it possible to change the package of an already published application on Google Play?

No, applicationId is a unique identifier for the application in the store. If you change it, Google Play will treat your app as completely new and you won't be able to update the existing version. Users will have to delete the old application and download a new one, and all statistics and reviews will be lost.

Why does Android Studio not see classes after renaming folders?

Most likely, you renamed the folders manually through the explorer, and not through the tool Refactor. In this case, the code inside the files still references the old packages in statements import. Use Refactor → Rename or perform global text replacement with care, and then do Invalidate Caches.

What is the difference between applicationId and package name?

applicationId (in build.gradle) is a unique ID for the Android system and store by which the device identifies the application. package name (in manifest and code) is a Java/Kotlin namespace for organizing code. They may coincide, but technically these are different entities, and you can only change the first one for different versions (build variants).

Do you need to change the package name for different versions of the application (Debug/Release)?

Yes, this is a common practice. You can configure different applicationId for build types in build.gradle (for example, com.example.app and com.example.app.debug). This will allow you to install the debug and release versions on the same device at the same time without conflicts.

How to fix the "Manifest merger failed" error after changing the package?

This error often occurs due to a conflict between applicationId in Gradle and package in Manifest. Make sure they are consistent, or use the namespace property in Gradle to explicitly specify the package, removing the package attribute from the tag manifestif your version of Gradle Plugin supports it.