Complete Guide to Package Renaming in Android Studio

To rename packages in Android Studio, you can use the built-in refactoring features by right-clicking on the package name and selecting “Refactor → Rename” or using the Shift + F6 shortcut. While Android Studio does provide automatic refactoring capabilities that update references across Java files and manifest files, it’s not as straightforward as Eclipse’s one-click operation and often requires manual updates to build.gradle files. For more comprehensive bulk operations, you can disable the “Compact Empty Middle Package” setting to access individual package components or use the dedicated Android Package Renamer plugin for safer, faster renaming.

Contents

• Basic Package Renaming Methods
• Bulk Refactoring Operations
• Step-by-Step Package Renaming Process
• Handling Gradle and Manifest Files
• Using the Android Package Renamer Plugin
• Best Practices and Common Issues

Basic Package Renaming Methods

Android Studio, being based on IntelliJ IDEA, provides several methods for renaming packages:

Using Keyboard Shortcuts

The most efficient way to rename a package is to place your cursor in the package name (don’t select it, just position the cursor) and press Shift + F6. This opens a rename dialog where you can enter the new package name and configure the refactoring scope source.

Using Context Menu

Alternatively, you can right-click on the package name in the project structure and navigate to Refactor → Rename. This method provides the same functionality as the keyboard shortcut but can be more discoverable for new users source.

Refactoring Dialog Options

When the rename dialog appears, you can:

• Type the new package name
• Specify additional options like search scope
• Choose whether to rename all occurrences or just the selected element
• Preview changes before committing

Important: The refactoring feature in Android Studio is designed to be safe and will show you all affected files before applying changes.

Bulk Refactoring Operations

While Android Studio doesn’t offer the same one-click simplicity as Eclipse for package renaming, it does provide robust bulk refactoring capabilities:

Scope Configuration

The rename refactoring allows you to specify the scope of changes:

• Directory only: Renames just the folder structure
• All references: Updates all references to the package name throughout the project
• Module and directory: Renames both the module name and directory simultaneously source

Project View Configuration

To access individual package components for bulk renaming:

1. Switch to Project view (if not already there)
2. Go to settings and deselect “Compact Empty Middle Package”
3. This breaks the package folder into individual components (com, example, app, etc.)
4. You can then rename each component individually using the refactoring tools source

Automatic Updates

The bulk refactoring will automatically update:

• All Java and Kotlin files with package declarations
• Import statements
• References in XML files
• The AndroidManifest.xml package attribute

However, certain files like build.gradle may require manual attention source.

Step-by-Step Package Renaming Process

Here’s a comprehensive workflow for renaming packages in Android Studio:

Preparation Phase

1. Backup your project: Always create a backup before performing major refactoring
2. Close unnecessary files: Reduces the risk of conflicts during refactoring
3. Ensure Gradle sync is complete: Prevents build-related issues

Package Structure Adjustment

1. Disable compact packages: In Android Studio settings, uncheck “Compact Empty Middle Package” under Editor → General → Appearance
2. Expand package structure: This allows you to see individual package components
3. Start from the top: Begin renaming from the root package (e.g., “com”) and work your way down source

Refactoring Execution

1. Right-click on the first package component (e.g., “com”)
2. Select Refactor → Rename
3. Enter the new package name (e.g., “io”)
4. Choose “Rename package” option in the dialog
5. Click Refactor to apply changes
6. Repeat for each package component in sequence

---

Example: Renaming from com.example.app to io.github.myapp

1. Right-click “com” → Refactor → Rename → “io”
2. Right-click “example” → Refactor → Rename → “github”
3. Right-click “app” → Refactor → Rename → “myapp”

This step-by-step approach ensures all references are properly updated throughout the project source.

Handling Gradle and Manifest Files

Gradle Files

After package refactoring, you’ll need to manually update:

1. applicationId in build.gradle:

   gradle

   android {
       defaultConfig {
           applicationId "io.github.myapp"  // Update to new package name
       }
   }
   

2. namespace in build.gradle (for newer Android Gradle Plugin versions):

   gradle

   android {
       namespace 'io.github.myapp'  // Update to new package name
   }
   

3. Sync Gradle: After making changes, sync your project with Gradle files

Manifest Files

The refactoring should automatically update:

• package attribute in AndroidManifest.xml
• However, verify that all references are correct after refactoring source

Build and Clean

After completing the renaming process:

1. Clean the project: Build → Clean Project
2. Rebuild the project: Build → Rebuild Project
3. Verify functionality: Test your app to ensure everything works correctly

Using the Android Package Renamer Plugin

For more efficient package renaming, consider using the Android Package Renamer plugin:

Plugin Features

• Safe and fast: Designed specifically for Android package renaming
• Comprehensive updates: Automatically handles all necessary file updates
• User-friendly: Provides a simpler interface than the built-in refactoring

Installation Steps

1. Go to File → Settings → Plugins
2. Click on Marketplace tab
3. Search for “Android Package Renamer”
4. Click Install and restart Android Studio

Usage

1. Right-click on your project or package
2. Select the plugin’s rename option
3. Follow the wizard to specify new package name
4. The plugin will handle all necessary updates automatically source

This plugin is particularly useful for complex projects where manual refactoring would be time-consuming and error-prone.

Best Practices and Common Issues

Best Practices

1. Test thoroughly: Always test your app after package renaming
2. Use version control: Commit changes incrementally to track modifications
3. Update dependencies: Ensure all library references are compatible with new package names
4. Check third-party integrations: Verify that Firebase, Google Play Console, and other services are updated

Common Issues and Solutions

Issue: Gradle Build Failures

Solution: Update applicationId and namespace in build.gradle files, then sync Gradle source.

Issue: Incomplete Reference Updates

Solution: Use the “Search Everywhere” feature (Shift+Shift) to find any remaining references to the old package name.

Issue: Manifest File Issues

Solution: Manually verify that the package attribute in AndroidManifest.xml matches your new package name source.

Issue: Module Naming Conflicts

Solution: When renaming modules, ensure you use Refactor → Rename rather than just renaming the folder to maintain proper project structure source.

Performance Considerations

• Large projects: May require more time for refactoring operations
• Complex dependencies: Might need additional manual verification
• Team collaboration: Ensure all team members are aware of the package name change

---

While Android Studio’s package renaming process requires more steps than Eclipse’s one-click solution, it provides powerful refactoring capabilities that ensure code consistency throughout your project. By following the proper procedures and using available tools, you can efficiently rename packages even in complex Android applications.

Sources

1. Rename package in Android Studio - Stack Overflow
2. How to rename package name in Android Studio | Code2care
3. How can I change top level package name in IntelliJ IDEA? - Stack Overflow
4. Rename refactorings | IntelliJ IDEA Documentation
5. Rename package in Android Studio | Bitcoden
6. Rename package in Android Studio | Edureka Community
7. Android Package Renamer Plugin for IntelliJ IDEA
8. How to rename package name in Android Studio | Medium
9. How to change the Package name in Android | Medium
10. A Step-by-Step Guide to Changing the Package Name of Your Android Kotlin Project | Medium

Conclusion

Android Studio provides robust package renaming capabilities through its IntelliJ IDEA-based refactoring tools, though they require more steps than Eclipse’s one-click approach. The key to successful bulk refactoring is disabling the “Compact Empty Middle Package” setting to access individual package components, using Shift + F6 or right-click Refactor → Rename for each component, and manually updating build.gradle files. For more efficient operations, the Android Package Renamer plugin offers a specialized solution. Always test thoroughly after renaming packages and use version control to track changes. While the process isn’t as streamlined as Eclipse, Android Studio’s refactoring tools ensure comprehensive updates across your project when used correctly.