Renaming a project in Android Studio is a task that every developer faces sooner or later. It would seem that what could be simpler than changing the name? However, in practice, this process is fraught with a lot of pitfalls: from incorrect operation R.java to problems with Gradle-synchronization. The topic is especially relevant for those who have inherited someone else's code, are rebranding an application, or simply realized that the original name com.example.myapp no longer reflects the essence of the project.

In this article we will analyze all possible renaming scenarios - from the basic shifts applicationId to a deep reorganization of packages and resources. You will learn how to avoid common mistakes (like assembly failure due to a mismatch of names in the manifest and Gradle), what tools Android Studio will make the process easier, and what to do if after renaming the application no longer starts. The material is relevant for Android Studio Giraffe (2022.3.1) and newer, but the basic principles apply to earlier versions as well.

1. Preparing for renaming: what needs to be done BEFORE the changes

Before you start changing the name, it is critical create a backup copy of the project. Even experienced developers sometimes miss dependencies or forget to update references in their code, resulting in hours of debugging. Use Git (command git commit -am "Backup before renaming") or simply copy the project folder to a separate location.

Next check:

  • 📁 Package structure: if the project uses a multi-module architecture, renaming the main module can affect dependent libraries.
  • 🔗 External dependencies: some SDKs (for example, Firebase or Google Mobile Ads) are tied to applicationId. They will have to be reconfigured.
  • 📱 Configuration files: google-services.json, AndroidManifest.xml, proguard-rules.pro —all of them may contain the old name.

☑️ Checklist before renaming

Done: 0 / 4

Pay special attention build.gradle (at the module level). If paths like src/main/java/com/oldname/...are hardcoded there, after renaming the packages the project simply will not build. Use relative paths or variables:

sourceSets {

main.java.srcDirs = ['src/main/java']


}

⚠️ Attention: If your project uses Dagger 2 or Hilt, after renaming the packages you will have to regenerate the injection components. Otherwise, the application will crash with an error No injectable members on ....

2. Renaming methods: from simple to complex

There are three main approaches to renaming a project in Android Studio, and the choice depends on what what exactly you want to change:

Purpose Method Complexity Potential risks
Change applicationId (for publication in Google Play) Editing build.gradle Low Conflicts with Google Play Console updating
Renaming packages (com.oldname → com.newname) Refactor → Rename in Android Studio Average Broken imports, errors in AndroidManifest.xml
Full reorganization (name + packages + resources) Manual editing + scripts High Broken links to resources, build crash

Let's start with the safest option - change applicationId. This is relevant if you want to publish the application under a new name in Google Play, but the internal structure of the code remains the same Open build.gradle (Module: app) and find the block:

defaultConfig {

applicationId "com.oldname.app"


...


}

Replace the value with a new one, for example:

applicationId "com.newname.app"

After that required execute:

  1. Synchronize the project with Gradle (button Sync Now in the top panel).
  2. Cache clearing (Build → Clean Project).
  3. Rebuilding (Build → Rebuild Project).
📊 Which renaming method do you use more often?
ApplicationId only
Refactor packages
Manual editing of all files
Never renamed

3. Renaming packages: step-by-step guide with pictures

If you need to change more than just applicationId, but also package name in code (for example, from com.oldcompany.app to com.newcompany.app), use built-in refactoring Android Studio. This method is the least error-prone because the IDE automatically updates imports and links in the manifest.

Action:

  1. Open project panel (usually on the left) and select view Android.
  2. Find the root package of your project (for example, com.oldname.app).
  3. Right-click on it and select Refactor → Rename.
  4. Enter a new package name (for example, com.newname.app) and click Refactor.
  5. In the window that appears, select the option Search in comments and strings (this will help find mentions of the old name in lines and comments).
  6. Confirm the changes and wait until the process completes.

After refactoring Android Studio automatically will update:

  • 📄 Names of packages in files .java/.kt.
  • 📋 Imports in classes.
  • 📜 Links in AndroidManifest.xml.
  • 🔧 Paths in build.gradle (if they were registered relative to the packages).
💡

If the project does not build after refactoring the packages, check the file imports.xml in the folder .idea. Sometimes the old class paths remain there.

However, even this method is not ideal, for example, if there are hardcode lines with the package name (for example, for dynamically loading classes), you will have to edit them manually. Use the project search (Ctrl+Shift+F) with a request for the old package name to find all references.

4. help

In some cases, automatic refactoring does not cope with the task. This is true for:

  • 🧩 Multi-module projects, where dependencies between modules are specified using absolute paths.
  • 🔄 Projects with native code (JNI), where paths to packages can be hardwired in CMakeLists.txt.
  • 📦 Librariesthat use package-name as part of the API.

For manual editing, follow this algorithm:

  1. Update AndroidManifest.xml: 
    <manifest package="com.newname.app" ...>

    Make sure that the attribute package in the tag <manifest> matches the new name.

  2. Edit build.gradle:

    Besides applicationId, check the blocks sourceSets and androidTest.

  3. Update the paths in the resources:

    If there are links to classes in res/values/strings.xml or other XML files (for example, for custom views), replace them:

    <com.oldname.app.CustomView /> → <com.newname.app.CustomView />
  4. Check proguard-rules.pro:

    If there are rules of the form -keep class com.oldname.app.** { *; }, update them.

To speed up the process, you can use regular expressions in search/replace (Ctrl+Shift+R). For example, to replace all imports:

  • Search: import com\.oldname\.app\.
  • Replacement: import com.newname.app.
⚠️ Attention: If your project uses Room Database, after renaming the packages you will have to increase the database version in @Database and provide migration. Otherwise, the application will crash when trying to access the database.

5. Renaming resources and other files

Sometimes, along with the project name, it is necessary to update and resource names (for example, if they contained a brand in the name: oldname_logo.png → newname_logo.png). The main rule here is do not break links in code and XML files.

How to rename resources safely:

  1. Open the folder res in the project.
  2. Select the files that need to be renamed (for example, ic_old_logo.xml).
  3. Click Shift+F6 (or right-click → Refactor → Rename).
  4. Enter a new name and confirm.

Android Studio will automatically update all links to the resource in:

  • 📄 layout/ files (for example, android:src="@drawable/ic_old_logo" → android:src="@drawable/ic_new_logo").
  • 📝 Java/Kotlin code (for example, R.drawable.ic_old_logo).
  • 🎨 styles.xml and themes.xml.

If you rename entire folders inside res (for example, drawable-old → drawable-new), do this carefully: some tools (for example, Data Binding) may generate incorrect links after renaming:

  1. Execute Build → Clean Project.
  2. Restart Android Studio (sometimes the IDE cache is not updated immediately).
  3. Check the build logs for errors like this cannot find symbol.
What to do if after renaming resources the application crashes?

The most common reason is a mismatch of names in the generated class. R.java. Try:

1. Delete the folder build manually.

2. Execute File → Invalidate Caches / Restart.

3. If used View Binding, check that all links in the XML match the names in the code.

6. Checking functionality after renaming

Even if the project was built successfully, this does not guarantee that everything works correctly. Carry out Full testing according to this checklist:

Component What to check How to check
Launch applications The application opens without crashing Run on an emulator or device
Working with the network API requests are executed correctly Check logs in Logcat (filter: OkHttp or Retrofit)
Local DB Data was not lost, migrations completed Open Database Inspector in Android Studio
Push notifications Topics Firebase Cloud Messaging updated Send test notification via Firebase Console
Deep Links Links like newname://... open Check via adb shell am start -a android.intent.action.VIEW -d "newname://test"

Pay special attention integrations with external services:

  • 🔥 Firebase: update file google-services.json (download a new one in the console Firebase with new package_name).
  • 📊 Google Analytics: check that events are sent to the correct project.
  • 💳 Payment systems (Google Play Billing): update applicationId in the product settings.

If after renaming you plan to publish an update to Google Play, please note:

  • 📦 applicationId must match what is specified in Google Play Console.
  • 🔑 If you change package name, this is considered a new application (updating an existing one is impossible!).
  • 🔄 To change package name without losing users you will have to use Android App Bundle i mechanism versionCode.
💡

If you only change the applicationId and leave the package name the same, the update in Google Play will take place without problems. But if you changed the package name, this is a different application, and users will not receive an automatic update.

7. Typical mistakes and how to avoid them

Even experienced developers encounter problems after renaming. Here are the most common errors and ways to solve them:

Error Cause Solution
Error: Package name 'com.oldname.app' used in: ... Old links remain in AndroidManifest.xml or build.gradle Search by project (Ctrl+Shift+F) with filter com.oldname
Cannot resolve symbol R Mismatch of package names in R.java and source codes Delete folder build, rebuild the project
java.lang.ClassNotFoundException Hardcode class paths in native code or reflection Update paths in CMakeLists.txt or System.loadLibrary()
Failed to resolve: com.newname.app:library Dependencies between modules are broken Check settings.gradle and build.gradle dependent module
The application crashes on startup Not updated ProGuard/R8 rules Check proguard-rules.pro for mentions of the old package

One of the most insidious errors is problems with Data Binding. If you are using data binding, you may receive an error after renaming packages:

Error: Cannot find the setter for attribute 'app:someProperty'

This is because the generated binding classes (ActivityMainBinding) contain old paths. Solution:

  1. Delete the folder build.
  2. Run Build → Clean Project.
  3. Restart Android Studio.
  4. If the error persists, check that the build.gradle option is enabled: 
    android {

    ...
    

    buildFeatures {
    

    dataBinding true
    

    }
    

    }

Another common problem is not working BroadcastReceiver or Service. If they are registered in the manifest with full paths:

<receiver android:name="com.oldname.app.MyReceiver" />

they will have to be updated manually. Use search by AndroidManifest.xml with filter android:name="com.oldname.

8. Automation of renaming: scripts and plugins

If you have to rename projects often (for example, when working with templates), it makes sense to automate the process. Here are a few tools that will help save time:

  • 🤖 Gradle script for bulk replacement:

    Add to build.gradle a task to replace imports:

    task replacePackageName {

    doLast {
    

    def oldPackage = 'com.oldname.app'
    

    def newPackage = 'com.newname.app'
    

    def dir = file("src/main/java")
    

    dir.eachFileRecurse { file ->
    

    def text = file.text.replaceAll(oldPackage, newPackage)
    

    file.write(text)
    

    }
    

    }
    

    }

    Run it via the command line:

    ./gradlew replacePackageName
  • 🔧 Plugin Android Package Renamer:

    Install the plugin via File → Settings → Plugins i use it for batch renaming.

  • 📦 Script for updating imports.xml:

    If after refactoring there are still broken links, this script will Python help fix them:

    import xml.etree.ElementTree as ET

    tree = ET.parse('.idea/imports.xml')
    

    root = tree.getroot()
    

    for entry in root.findall('entry'):
    

    old_path = entry.get('value')
    

    if 'com/oldname/app' in old_path:
    

    entry.set('value', old_path.replace('com/oldname/app', 'com/newname/app'))
    

    tree.write('.idea/imports.xml')

For projects with Flutter or React Native The renaming process is different. For example, in Flutter you need to edit:

  • 📝 android/app/build.gradle (change applicationId).
  • 📱 android/app/src/main/AndroidManifest.xml (attribute package).
  • 🐵 ios/Runner.xcodeproj/project.pbxproj (for the iOS part).

If you are working with Kotlin Multiplatform Mobile (KMM), renaming packages will require additional actions in the general module (shared). Update:

  • 📦 Package names in commonMain i androidMain.
  • 🔗 Links in build.gradle.kts (if used sourceSets).
  • 🔧 Configuration Cocoapods for the iOS part (file Podfile).
💡

For projects with native code (JNI/NDK), after renaming the packages, be sure to update the paths in CMakeLists.txt and rebuild the libraries.

FAQ: Answers to frequently asked questions

Is it possible to rename a project without breaking existing settings for users?

Yes, but only if you change only applicationIda package name leave it the same. In this case, users will receive the update via Google Play as usual. If you change package name, it will be considered a new application and users will have to install it separately.

To avoid losing users, use the mechanism Android App Bundle configure versionCode so that it is higher than the current version. You can also add a dialog to the old application asking you to switch to the new one.

After renaming the packages, @StringRes and other annotations stopped working. What to do?

This is a typical problem associated with the fact that Android Studio does not always update generated classes correctly. Try:

  1. Delete folder build manually.
  2. Run File → Invalidate Caches / Restart.
  3. If that doesn't help, check that build.gradle the option is enabled: 
    android {

    ...
    

    compileOptions {
    

    sourceCompatibility JavaVersion.VERSION_1_8
    

    targetCompatibility JavaVersion.VERSION_1_8
    

    }
    

    }

If the problem persists, perhaps the code contains imports of the form import com.oldname.app.R. Replace them with import com.newname.app.R.

How to rename a project if it uses Dagger 2?

When using Dagger 2 after renaming packages you must:

  1. Update annotations @Module and @Componentif they contain full class paths.
  2. Regenerate injection classes (Build → Make Project).
  3. If you use @BindsInstance or @IntoMap, check that the keys (for example, @ClassKey) do not contain the old paths.

Typical error after renaming: 

error: [dagger.android.AndroidInjector.inject(T)] ... cannot be provided without an @Inject constructor or an @Provides-annotated method.

It means that Dagger cannot find the class in the new path. The solution is to clean the project and regenerate the code.

Is it possible to rename a project via terminal?

Yes, but it is risky as it is easy to miss some files. If you still want to use the terminal, here is an example command for replacing imports in files .java i .kt:

find . -type f \( -name ".java" -o -name ".kt" \) -exec sed -i 's/com\.oldname\.app/com.newname.app/g' {} +

However, this method does not update:

  • 📄 AndroidManifest.xml;
  • 📦 build.gradle;
  • 🔧 Resource files (res/).

Therefore, it is better to use it only for bulk replacement in the sources, and edit the remaining files manually or through refactoring in Android Studio.

What to do if Deep Links stop working after renaming?

Deep Links are tied to package name i host to AndroidManifest.xml. After renaming:

  1. Update android:scheme and android:host in <intent-filter>: 
    <intent-filter>

    <action android:name="android.intent.action.VIEW" />
    

    <category android:name="android.intent.category.DEFAULT" />
    

    <category android:name="android.intent.category.BROWSABLE" />
    

    <data
    

    android:scheme="https"
    

    android:host="newname.com" />
    

    </intent-filter>

  2. If you use Firebase Dynamic Links, update the domain in the console Firebase.
  3. Check that new package name indicated in digital_asset_links.json (if you use App Links).

For testing, use the command:

adb shell am start -a android.intent.action.VIEW -d "newname://test"