Comprehensive Guide to Changing Package Name and App Name in Flutter Projects

Introduction

In Flutter development, package names and application names serve as crucial identifiers for projects. The package name uniquely identifies an application in app stores, while the application name is the visible name presented to users. Since Flutter automatically generates default package names (e.g., com.example.appname) during project creation, developers often need to modify these according to project requirements.

Package Name Modification for Android Platform

Modifying package names on the Android platform requires coordinated updates across multiple configuration files to ensure consistency.

Application Name Modification

Changing the application name is relatively straightforward and involves updating the label attribute in the AndroidManifest.xml file:

<application
  android:name="io.flutter.app.FlutterApplication"
  android:label="Your App Name">
</application>

The label value here determines the name displayed for the application on devices.

Package Name Modification

Package name changes require synchronized updates across the following files:

1. AndroidManifest.xml Files

Update the package attribute in android/app/src/main/AndroidManifest.xml, android/app/src/debug/AndroidManifest.xml, and android/app/src/profile/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="your.new.package.name">

These three files correspond to different build environments (main, debug, and profile), and consistency across all environments is essential.

2. build.gradle File

Update the applicationId in android/app/build.gradle:

defaultConfig {
    applicationId "your.new.package.name"
    minSdkVersion 16
    targetSdkVersion 27
    versionCode 1
    versionName "1.0"
    testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
}

The applicationId serves as the package identifier for the Gradle build system and must match the package in AndroidManifest.

3. MainActivity File

Update the package declaration in the appropriate MainActivity file based on the project's language (Java or Kotlin):

package your.new.package.name;

import android.os.Bundle;
import io.flutter.app.FlutterActivity;
import io.flutter.plugins.GeneratedPluginRegistrant;

public class MainActivity extends FlutterActivity {
    // Class content
}

4. Directory Structure Adjustment

Rename the Java/Kotlin source code directory to match the new package path:

From: android/app/src/main/java/com/example/name

To: android/app/src/main/java/your/new/package/path

For example, if the new package name is com.company.app, the directory should become android/app/src/main/java/com/company/app.

Package Name Modification for iOS Platform

For the iOS platform, the package name corresponds to the Bundle Identifier, which needs modification in the ios/Runner/Info.plist file:

<key>CFBundleIdentifier</key>
<string>com.yourdomain.appname</string>

The Bundle Identifier uniquely identifies the application in the App Store, typically following reverse domain name notation.

Command-Line Project Creation with Specific Package Names

To avoid the complexity of manual modifications, you can specify the package name during project creation:

flutter create --org com.yourdomain appname

This command creates a Flutter project with the package name com.yourdomain.appname. For example:

flutter create --org com.example myapp

creates a project with the package name com.example.myapp.

If you prefer Java over Kotlin for Android development, add the -a java parameter:

flutter create -a java --org com.yourdomain appname

Third-Party Tool Assistance

Beyond manual modifications and command-line creation, third-party packages can simplify the package name change process:

flutter pub run change_app_package_name:main com.package.appname

This command automatically updates all relevant package name configurations in the project, reducing potential errors from manual operations.

Important Considerations

When modifying package names, consider the following:

1. Ensure complete consistency across all related files to avoid build errors from mismatches.

2. If the project is connected to third-party services like Firebase, verify that the package name matches the one registered with those services.

3. After changing the package name, you may need to regenerate signing keys and republish the application.

4. For already published applications, package name changes typically require republishing as a new application.

Conclusion

While modifying package names and application names in Flutter projects involves coordinating multiple configuration files, following the correct steps ensures successful completion. It's advisable to plan appropriate package names during the initial project phase or use the flutter create --org command to create projects with specific package names directly, avoiding subsequent modification work. For existing projects, choose between manual updates or third-party tools to streamline the process.