One Flutter app, five "package names" (and the one to leave alone)

"Just change the package name" sounds like a one-line edit. In a Flutter project, five different things answer to that name. Four of them should change when you rename an app. One usually should not.

The five names

Name	Where it lives	What it does	Change it?
applicationId	android/app/build.gradle.kts (or build.gradle)	The ID Google Play and Android devices use to identify the app	Yes
namespace	Same file, android block	Kotlin/Java package for generated classes like R and BuildConfig	Yes, keep it equal to applicationId
MainActivity package	android/app/src/main/kotlin/...	The package line and folder path of the activity Flutter starts	Yes, must match namespace
PRODUCT_BUNDLE_IDENTIFIER	ios/Runner.xcodeproj/project.pbxproj	The iOS bundle ID	Yes
name:	pubspec.yaml	The Dart package name used in package: imports	Usually no

Android: three places that must agree

// android/app/build.gradle.kts
android {
    namespace = "com.yourcompany.yourapp"

    defaultConfig {
        applicationId = "com.yourcompany.yourapp"
    }
}

// android/app/src/main/kotlin/com/yourcompany/yourapp/MainActivity.kt
package com.yourcompany.yourapp

import io.flutter.embedding.android.FlutterActivity

class MainActivity : FlutterActivity()

The folder path has to change too: kotlin/com/yourcompany/yourapp/. If the package line and the folder disagree with namespace, the build or the app launch fails.

The gotcha

Android lets namespace and applicationId differ, but recommends keeping them the same. And if applicationId isn't set explicitly, it takes the namespace value. So changing one can silently change the other. Set both, explicitly, to the same value.

iOS: one setting, several build configurations

The bundle ID lives in PRODUCT_BUNDLE_IDENTIFIER inside project.pbxproj, once per build configuration (Debug, Release, Profile). The safest way to change it is in Xcode: open ios/Runner.xcworkspace, select the Runner target, and edit the Bundle Identifier on the General tab so every configuration is updated.

Dart: why pubspec.yaml's name usually stays

The name: in pubspec.yaml is what every import in your app uses:

import 'package:my_app/screens/home_screen.dart';

Renaming it means rewriting every one of those imports. It is not what the stores see, so for a rename or a rebrand, leave it alone. Users never see it.

Two things to do before you rename

1. Pick the final ID before the first store upload. Once an app is published on Google Play, its application ID can't change. A "temporary" ID becomes permanent the moment you publish.
2. Plan for Firebase. A Firebase Android app's package name can't be changed after registration, and neither can an Apple app's bundle ID. After a rename, register new apps under the new IDs and run flutterfire configure again. A stale google-services.json gives a loud "No matching client found" build error, which is the easy case.

After the rename

Clean and rebuild, then test a release build on a real device, not just a debug run:

flutter clean
flutter pub get
flutter build apk --release

The quiet failures (Google Sign-In, Maps, push notifications) only show up when the new ID meets services that were registered under the old one.

---

Further reading: the step-by-step guide, with backups and real-device checks, is in our help center: Changing your app's package name.

Have you ever shipped an app under a placeholder ID by accident?