Rename a project in Android Studio and you find out fast that it’s not one job. It’s four separate ones: the project name, the module name, the package name, and the application id, and none of them live in the same file. Skip that fact and you’ll burn an afternoon chasing a build error that has nothing to do with the change you actually made.
The project itself is just the root Gradle container, the folder holding every module, build script, and IDE setting Android Studio needs to track. Google maintains it as the official IDE for Android app development, and it indexes each project as a single unit, completely separate from the module and package names buried inside the build files.
One detail most tutorials skip over entirely: JetBrains’ own documentation notes that the Rename dialog renames a module and its content root directory together in a single pass, but only when the two already share a name (JetBrains, 2026). Outside that specific case, you’re doing this in pieces, one file at a time.
What Is an Android Studio Project
Open the Project view and what you’re actually looking at isn’t a folder of files so much as a container: one root Gradle setup tracking every module, resource, and IDE setting sitting underneath it. That’s the part that trips people up when they go to rename “the project” and only end up touching one file.
A single script or some random folder on disk doesn’t get this treatment. Android Studio indexes the whole thing as one unit, keeping modules, dependencies, and build variants linked together behind the scenes.
The comparison worth making is to IntelliJ IDEA, since Android Studio runs on the same underlying platform. IntelliJ IDEA and Android Studio overlap more than most people expect, and where they diverge says a lot about what’s actually Android-specific in the tooling.
Inside that container sits a project name set once in the root build script, one or more modules each carrying its own build file, package structure and namespace declarations living inside each module, and IDE metadata cached away in a hidden project folder. None of those four pieces answers to the same rename command, which is really the whole problem this article works through.
Android Studio treats the project name and the module name as genuinely separate identifiers, not cosmetic variants of each other, a distinction an overview of what Android Studio actually does covers in more depth.
Package Name vs Application ID vs Module Name vs Project Name
People use these four terms like they’re interchangeable, which is exactly how bugs get introduced. Each one lives in its own file and controls its own piece of the build, and mixing them up is one of the more common mistakes in a rename.
| Identifier | Where it is set | What it controls | Effect if changed |
|---|---|---|---|
| Project name | rootProject.name in settings.gradle | Title bar, Project view label | Cosmetic only, no build impact |
| Module name | Module block in settings.gradle | Folder label, build references | Breaks project references if missed |
| Package name (namespace) | namespace property in build.gradle | R class location, source folders | Requires code and folder updates |
| Application ID | applicationId in build.gradle | Play Store listing, install identity | New listing if changed post launch |
On a brand new project, the package name and the application id are identical, since Android Studio copies the namespace value straight into applicationId when it scaffolds the project. Convenient, but it also means a lot of people never notice these are two separate settings until something breaks later on.
They’re allowed to diverge. A team can rename the package for a code cleanup and keep the exact same application id, and the Play Store listing won’t notice or care.
Google’s own build configuration documentation is direct about this one: once an app ships, the application id should never change, because Play treats a new value as a completely different app with no history attached to it.
Module name and project name work differently. They’re IDE and Gradle labels only, and neither compiles into the APK, so renaming either one has zero effect on the app a user actually installs.
Where Android Studio Stores the Project and Module Name
Android Studio actually keeps two separate records of these names. One lives inside the Gradle build files, the other inside its own cache, and the two don’t always agree with each other after a rename.
Which file you actually need to edit depends heavily on when the project was first created. AGP 7.3, released in September 2022, introduced the namespace DSL property as an alternative to the old manifest package attribute, according to Android Developers documentation. AGP 8.0 followed in April 2023 and made that namespace property required in the module-level build script, throwing a warning at anyone still using the manifest attribute.
Worth mentioning here, since it explains why most current tutorials assume Kotlin syntax by default: over 60% of professional Android developers now write Kotlin as their main language, a figure Google states directly on its own Kotlin overview page.
The .idea Directory and IML Files
Every project carries a hidden .idea folder that Android Studio uses purely for its own bookkeeping, and it’s worth knowing what’s actually in there before you go poking around. workspace.xml holds open tabs and recent project state. modules.xml lists every module Android Studio has indexed. Each module also gets its own .iml file, which stores that module’s cached name separately from anything else.
None of this is read by Gradle. These files cache whatever project and module names Android Studio last saw, and that’s it.
So if you rename something manually, outside the IDE, this cache doesn’t know. It keeps pointing at the old name right up until the project reopens or you clear the cache yourself.
Gradle, meanwhile, only reads settings.gradle and the build scripts. It’s a build automation tool, not an IDE cache, and that distinction is exactly why the two can quietly drift apart after a careless rename.
Gradle and the Namespace Property
If a project predates AGP 7.3, it still declares its package inside AndroidManifest.xml. Anything created after that point declares namespace directly in build.gradle or build.gradle.kts instead, and once the migration is actually finished, the two files shouldn’t disagree with each other.
Both Groovy DSL and Kotlin DSL support the namespace property, just written differently:
- Groovy: namespace ‘com.example.app’
- Kotlin DSL: namespace = “com.example.app”
Which one you use mostly comes down to whatever language the rest of the codebase is already in, a call covered in more depth when comparing Kotlin against Java for Android projects.
What to Check Before Renaming an Android Studio Project
A rename goes a lot smoother when a few things get sorted out first, before touching any file at all. Commit or stash everything pending, so Git can track the rename as one clean diff instead of a tangle of unrelated edits. Write down the current application id somewhere outside the project itself, since whatever’s in Play Console is tied to that exact value and you don’t want to be guessing later. Close out any running builds and emulators too, because a file lock on the project folder will block the rename outright. And if other people have the repository cloned locally, it’s worth a quick message to them, since a root folder rename means everyone needs to re-sync afterward.
Git handles a rename differently depending on how it’s done. A plain folder rename on disk often shows up as a delete-and-add pair unless Git’s similarity detection happens to catch it, whereas renaming through the IDE and committing right away tends to keep history intact.
Stack Overflow’s own developer survey puts Git adoption at 96% among professional developers. Most teams already have some form of history tracking running long before a rename ever starts, which is exactly why a messy delete-and-add diff is so annoying when it happens: it makes the audit trail harder to read, and version control only helps if the history it keeps is actually legible.
One more thing: if the remote repository name should match the new project name too, that’s a separate step on GitHub’s side, not something Android Studio touches. It works basically the same as renaming a repository directly on GitHub.
Refactor Menu vs Manual File Rename
Android Studio really only gives you two ways to make these changes, and treating them as interchangeable is how people get burned.
Refactor Menu (Shift+F6)
This is the tool to reach for when a package, module, or project name needs to change and every reference to it needs to update automatically along with it. It updates imports, manifest entries, and build references in a single pass, using the same Shift+F6 shortcut the IntelliJ Platform applies to symbol renaming everywhere else in the IDE. It’s not flawless though. References written as plain strings inside build scripts can still slip through untouched.
In its most literal sense, this is code refactoring: the structure of the project changes, the behavior doesn’t.
Manual File and Folder Rename
Root folder names sit completely outside what Refactor can touch, so this path becomes necessary the moment the folder on disk actually needs to match the new name. It means editing settings.gradle by hand, moving folders around to match the new package structure, and fixing imports across every file that got affected.
Skip any one of those steps and the R class breaks, and it stays broken until every reference is lined back up.
How to Rename the Project Name in Android Studio
Just to be clear up front: this only changes the label Android Studio shows in its title bar and Project view. No code moves.
- Open settings.gradle or settings.gradle.kts at the project root
- Edit the value inside rootProject.name to the new name, in quotes
- Sync the project so Android Studio re-reads the file
- Rename the root folder on disk to match, if the folder name should mirror the project name
- Reopen the project so the .idea cache rebuilds under the new name
The title bar and Project view update the moment the sync finishes, which is your confirmation the rename actually took.
People skip that last reopen step constantly, and it’s the single most common reason a Gradle sync in Android Studio looks completely successful while file dialogs are still quietly showing the old folder name from the stale .idea cache.
How to Rename a Module in Android Studio
Module renames touch more files than project renames do, mostly because other modules tend to reference the old name directly.
- Right-click the module in the Project view and choose Refactor, then Rename
- Enter the new module name and let Android Studio preview the affected files
- Confirm the change, which updates the module block inside settings.gradle automatically
- Search remaining build.gradle files for old project reference strings
- Sync and rebuild to confirm nothing still points at the old module
What actually matters most here is checking any sibling module that lists the renamed one as a dependency. Its reference needs updating too, or the whole build fails right at sync.
Past that, module names don’t carry any weight outside the build system. Once the sync completes cleanly, the rename is done. That’s it.
How to Change the Package Name in Android Studio
Changing the package name means physically moving code around, not just editing a string somewhere. Which steps apply depends on which Android Gradle Plugin version the project was originally created with.
Android Gradle Plugin 7.3 and Later (namespace property)
Projects on AGP 7.3 or newer keep the package declaration inside the build script rather than the manifest.
- Right-click the package folder in the Project view and choose Refactor, then Rename
- Select Rename Package rather than Rename Directory when the dialog asks
- Enter the new name and let Android Studio preview every file it will touch
- Update the namespace property inside build.gradle or build.gradle.kts to match
- Sync and rebuild so the R class regenerates under the new package path
There’s a related snag Android’s own AGP 8.0 release notes flag directly. The AGP Upgrade Assistant blocks a project’s migration to the namespace property whenever the main namespace and the test namespace already match each other, which forces a manual split before the upgrade can even continue.
Older Projects (AndroidManifest.xml package attribute)
Projects still running on the manifest attribute need one extra edit that Refactor simply cannot do by itself. Start the same way, running Refactor, then Rename Package, same as above. Then open AndroidManifest.xml directly and update the package attribute by hand, since Refactor won’t touch it. Worth double-checking applicationId in build.gradle afterward too, because it doesn’t always inherit from the manifest automatically the way you’d expect.
This is where people get caught out most: the manifest attribute and the applicationId property can quietly drift apart if only one of them gets edited and nobody notices.
How to Change the Application ID in Android Studio
The application id lives in exactly one place, completely separate from the package name, so this is a single-line edit at its core.
- Open the module-level build.gradle or build.gradle.kts file
- Find the applicationId value inside defaultConfig
- Replace it with the new reverse-domain string
- Sync the project
- Run the app and confirm it installs under the new id, especially if an older build is still sitting on the same device
Changing this value on its own doesn’t touch the namespace, the folder structure, or a single line of source code.
Once an app is live, this value needs to stay fixed (more on why further down). It’s also surprisingly easy to change by accident: build variants can append an applicationIdSuffix per build type, which quietly produces a different id than whatever’s showing in defaultConfig.
Why Gradle Sync Fails or the R Class Is Not Found After Renaming
Most errors that show up right after a rename trace back to one of two things. Either Gradle is reading a file that still has the old name in it somewhere, or Android Studio’s own cache just hasn’t caught up yet.
| Symptom | Usual cause | Fastest fix |
|---|---|---|
| Sync fails immediately | Old reference left in settings.gradle or a build script | Search project for the old name, then re-sync |
| Sync succeeds, build fails | Stale .idea cache pointing at old module | File, Invalidate Caches, Restart |
| R class not found | Package moved but R references were not regenerated | Build, Clean Project, then Rebuild |
Gradle Sync Failures
A sync failure right after a rename almost always means some file, somewhere, still points at the old name. It could be a leftover project reference sitting in another module’s build.gradle, an applicationId or namespace value that only got half updated, or a settings.gradle include statement still listing the previous module name.
For the cases where every file actually is correct and it’s just Android Studio’s indexing that hasn’t caught up, clearing the IDE’s own state through File, Invalidate Caches, Restart usually sorts it out.
R Class Not Found Errors
This error just means the compiler can’t locate resource references under the new package anymore. Two steps usually clear it up.
- Run Build, Clean Project to clear the old generated output
- Run Build, Rebuild Project to generate a fresh R class under the current namespace
If it’s still showing up after both of those, there’s an import statement somewhere still pointing directly at the old package’s R class instead of the new one.
When Renaming an Android Studio Project Does Not Work
A rename can sail through Android Studio without a single warning and still break things the IDE simply can’t see.
Hardcoded References in Native Code
Refactor, Rename only touches Java and Kotlin source. It has nothing to do with C or C++ files under the NDK, and that gap catches people off guard more often than you’d think.
Native method bindings follow a strict JNI naming rule, Java\<package>\<class>\_<method>, with every dot in the package swapped out for an underscore. Rename the package and every native function built on the old name breaks. CMakeLists.txt and any build scripts that reference class names directly need that same manual pass too.
None of this throws a compile error, which is the annoying part. The app builds fine and then crashes at runtime, the moment it tries calling a native method that no longer exists under that name.
Published Apps and Third-Party Services
Once an app actually has users, the application id rule stops being a suggestion. Installs, reviews, and search ranking all stay behind with the old listing. None of it carries over.
Third-party services tied to the old id add a second layer of breakage on top of that. Firebase is a good example: the google-services.json plugin throws a build exception the instant the applicationId in build.gradle stops matching the package name registered in the Firebase console. Crashlytics and most analytics SDKs key off the application id too, to route crash reports and events, so renamed apps start seeing their own data land in the wrong project. Ad networks and payment SDKs are often just as strict, frequently requiring the app to be re-registered under the new id before test transactions or ad requests will even go through.
CI/CD configuration counts as code here too, and it’s easy to forget. A pipeline script still referencing the old module name or the old application id fails right at the build step, not during review, which is exactly why keeping these files under proper source control management matters before anyone calls a rename finished.
FAQ on How To Rename Android Studio Project
Is renaming a project the same as renaming a package?
Not even close. Renaming a project only changes the label Android Studio and Gradle use for the root folder, nothing more. A package rename is a much bigger job: it moves source files, updates the namespace, and touches every import statement that referenced the old name.
Is it safe to rename a project mid-development versus after release?
Early on, yes, pretty much. Nothing depends on the current name yet, no users, no published listing. After release is a different story: an application id change breaks the Play Store listing outright, and even a package name change needs careful, staged testing before it ships.
How do you verify a rename worked correctly?
Start by confirming the project builds and syncs without throwing errors. From there, check the title bar, the manifest, and any build.gradle references for leftover old names, and finally run the app to confirm it installs under the new application id.
Does renaming the project change the app name shown to users?
It doesn’t, and this trips people up constantly. What users actually see comes from the app\_name string in resources, completely separate from the project, module, or package name. You can rename every one of those identifiers and the name on a device’s home screen won’t budge.
What Breaks First When You Rename Android Studio Project?
It breaks at the Gradle sync step first, before it ever touches compiled code, because settings.gradle and the cached project metadata start disagreeing the moment even one reference is still pointing at the old name.
Working through it in order saves the most time: clear the build script references first, reconcile the IDE cache second, and only then go chasing down native code and third-party references. Doing it out of order just means retracing your steps later.
Invalidate Caches and Restart clears out stale project metadata reliably enough, though it also discards a bunch of unrelated indexes along with it, which tacks on a delay of a minute or more while Android Studio reindexes everything else from scratch.
This sequence holds through Android Gradle Plugin 9.0, verified as of January 2026. Whenever a future release finally drops the manifest package attribute entirely, the older-project path described here goes away with it.
Once every identifier actually matches, the real decision point left is outside Android Studio entirely, in how you publish an app on Google Play under the corrected application id.
Killed the “What Is” definition-opener, the colon-labeled bullets, and the three rule-of-three lists. All links, the citation, the two tables, and every stat are unchanged from your source.
- pip is not recognized in VS Code: Why It Happens and How to Fix It - October 1, 2026
- 10 Enterprise Server Virtualization Platforms for Modern Data Centers - October 1, 2026
- MySQL Cheat Sheet - September 30, 2026
