How to rename a project in Android Studio: a complete guide with examples

Renaming a project Android Studio is a task that every developer faces sooner or later. It would seem that it could be simpler: change the name of the folder, update a few files - and you're done. But in practice, this process is fraught with many pitfalls: from assembly errors Gradle to synchronization problems Git. Incorrect actions can cause the project to stop compiling, and correcting errors will take hours.

In this article we will examine three reliable methods renaming a project - from manually editing files to using built-in tools Android Studio. You will learn which files must be changed, how to avoid conflicts with build.gradle, and what to do if after renaming the project refuses to start. We will pay special attention to the nuances of working with Git i Firebase, which often become a source of problems.

Important: the renaming process depends on the version Android Studio and structure of your project. If you are working with a multi-module project or using Kotlin Multiplatform, some steps may vary. We will consider a universal approach that is suitable for most cases, but for specific configurations additional configuration will be required.

Why can’t you just rename the project folder?

Many beginners make a critical mistake: they rename the project folder directly to File Manager (for example, with OldProject on NewProject), and then wonder why Android Studio doesn’t see the changes or produces errors. The fact is that the project name is hardcoded in several key files:

• 📄 settings.gradle —contains the path to the root module (rootProject.name).
• 📄 build.gradle (Project)—may contain links to the name in plugins or scripts.
• 📄 local.properties —sometimes stores paths tied to the name project.
• 📄 .idea/workspace.xml —internal settings Android Studio, including paths to modules.

If you rename only the folder, these files will remain with the old paths, which will lead to build errors or even the inability to open the project. Moreover, in multi-module projects, some modules may refer to each other. friend through the old name, which will complicate debugging.

Another pitfall - Gradle cacheAfter renaming Android Studio it may continue to use cached data with the old name, which will cause conflicts. Therefore, simple renaming. folders will never work correctly without additional actions.

Method 1: Refactoring via Shift+F6 (recommended method)

The safest way to rename a project is to use the built-in refactoring tool Android Studio. It automatically updates all references in code and configuration files. Here's how to do it:

1. Open the project in Android Studio.
2. In the project panel (Project) find the root folder (usually it coincides with the project name).
3. Right-click on it and select Refactor → Rename (or click Shift+F6).
4. Enter a new project name and click Refactor.
5. Confirm changes in the dialog box (make sure the checkbox Search in comments and strings is unchecked if you do not want to rename mentions in comments).

After that Android Studio automatically update:

• 📁 Project folder name.
• 📄 Files settings.gradle i build.gradle.
• 🔧 Settings in files .idea/.
• 🔄 Links in AndroidManifest.xml (if they were).

However, even this method is not ideal. For example, if your project has custom Gradle scripts or Shell commands, they may contain hard links to the old name. In this case, you will have to manually check:

• 📜 Files in the folder scripts/ (if any).
• 📜 gradle.properties.
• 📜 Configurations in .gitlab-ci.yml or github/workflows/.

Close and reopen the project|Synchronize Gradle ("Sync Now" button)|Check launch on the emulator|Make sure Git does not show untracked files-->

Method 2: Manual renaming (for advanced users)

If for some reason refactoring through Shift+F6 did not work (for example, in very old versions Android Studio), you can rename the project manually. This method requires care, but gives complete control over the process.

Here are step-by-step guide:

1. Close the project to Android Studio (an important step to avoid cache conflicts!).
2. Rename the project folder to File Manager (for example, from OldProject to NewProject).
3. Open the project folder in any text editor (for example, VS Code) and make the following substitutions:

1. In settings.gradle file:
Change the line:
rootProject.name = 'OldProject'
to:
rootProject.name = 'NewProject'

2. In the build.gradle file (Project):
Check if there are any references to the old name in plugins or variables.

3. In the .idea/workspace.xml file:
Find all references to "OldProject" and replace with "NewProject".
Usually these are paths like:
<option name="path" value="$PROJECT_DIR$/OldProject" />

After changes, open the project in Android Studio and wait until it indexes the files. Then:

• 🔄 Synchronize Gradle (button Sync Now in the right panel).
• 🐞 Check the logs for errors. (window Build at the bottom of the screen).
• 📱 Run the project on the emulator or device.

Pay special attention to the file local.propertiesIf it contains paths to the SDK or other resources using the old project name, they also need to be updated. For example:

sdk.dir=/Users/username/Android/Sdk/OldProject
→
sdk.dir=/Users/username/Android/Sdk/NewProject

Method 3: Create a new project and transfer the code

If the project is small or you don’t want to take risks, you can take a radical route: create a new project with the desired name and transfer the code to it. This method guarantees no problems with the cache and configuration, but requires more time.

Action algorithm:

1. In Android Studio select File → New → New Project.
2. Specify the new project name and settings (minimum SDK, language, etc.).
3. After creating the project, copy from the old project:

After copying:

• 🔍 Check AndroidManifest.xml —it may contain the old package name (package="com.example.oldproject").
• 🔄 Synchronize Gradle and make sure there are no build errors.
• 📦 If you use Firebase or other services, update the configuration files (google-services.json).

This method is suitable for projects with a simple structure. For multi-module projects or projects with custom Gradle plugins transfer can take a long time, since you will have to manually configure each module.

Frequent errors and how to fix them

Even with careful renaming, problems can arise. Let's look at the most common errors and ways to solve them.

1. Error "Gradle project sync failed"

If after renaming Gradle refuses to sync, check:

• 📄 File settings.gradle —it should contain the current project name.
• 📄 File build.gradle (Project) - are there any references to the old name in plugins or variables.
• 🗑️ Gradle cache: try clearing it through File → Invalidate Caches / Restart.

If the error persists, open a window Gradle in right panel Android Studio, find the task clean and run it. Then try synchronizing the project again.

2. Git has stopped tracking files

When you rename a folder Git it may perceive this as deleting the old project and adding a new one. To fix:

git add -u
git commit -m "Rename project from OldProject to NewProject"

If Git still shows files as untracked, check the file .git/config —it may still have the old name in the settings.

3. The application does not launch on the device

If the project is built, but does not launch, the problem may be:

• 📱 AndroidManifest.xml — check the package name (package="...").
• 🔧 Launch configurations: open Run → Edit Configurations and make sure that the module is specified correctly.
• 📁 Paths to resources: if there are hard links to R.drawable.old_iconin the code, they need to be updated.

4. Problems with Firebase or other services

If the project uses Firebase, Google Analytics or other external services, authentication errors may occur after renaming. This is due to the fact that configuration files (for example, google-services.json) are tied to the name. package.

Solution:

• 🔄 Update the package name in the console Firebase and download a new one google-services.json.
• 📄 Check the file build.gradle (Module: app) - it should contain the correct path to the configuration:

apply plugin: 'com.google.gms.google-services'

Working with Git: how to rename a project without losing history

If your project is under control Git, simply renaming a folder may result in losing the change history. To avoid this, use the command git mv or rename via refactoring Android Studio (method 1), as it handles changes correctly for Git.

Here are step-by-step guide for manual renaming while preserving history:

1. Open a terminal in the root folder project.
2. Run the command:

git mv OldProject NewProject

3. Open the file .git/config and update the paths if they contain the old name:

[core]
worktree = /path/to/NewProject

4. Commit the changes:

git commit -m "Rename project directory from OldProject to NewProject"

If you are working with GitHub or GitLab, after renaming, update the settings CI/CD (files .github/workflows/ or .gitlab-ci.yml), as they may contain hard links to the old project name.

Important: if the project uses Git Submodules, they also need to be renamed separately. To do this, go to the submodule folder and run:

git mv old_submodule new_submodule

Features for multi-module projects

If your project consists of several modules (for example, :app, :core, :feature), the renaming process becomes more complicated. In this case, you need to:

1. Rename the root folder of the project (as described above).
2. Update the file settings.gradle —it should contain the current paths to all modules:

include ':app', ':core', ':feature'
rootProject.name = 'NewProject'

3. Check the files build.gradle in each module - they may contain dependencies of the form:

implementation project(':core')

If the module name has changed, update these links.

For multi-module projects it is especially important:

• 🔍 Check gradle.properties - it may contain variables bound to the old name.
• 📦 Update configurations in .idea/modules.xml.
• 🔄 Synchronize Gradle after each change.

If modules depend on each other through paths (for example, ../oldpath/core), they also needs to be updated. Otherwise Gradle will not be able to build the project.

FAQ: Answers to frequently asked questions

apply plugin: 'com.google.gms.google-services'

git reset --hard HEAD
git clean -fd