Package Name — what it is, reverse domain notation and requirements

What is Package Name in Android

Package Name is a unique string that Android uses to identify an application at the operating system level. It corresponds to the package field in the AndroidManifest.xml file and the applicationId field in the app module’s build.gradle file. Without a unique Package Name, installing an application on a user’s device is impossible.

Package Name Purpose

On the device, Package Name serves as a key for application management: the system stores data, settings, and cache for each application in the /data/data/[packageName] directory. Two applications with the same identifier cannot coexist — when attempting to install a duplicate, the system prompts to remove the existing one.

Package Name and Application ID

In Android Gradle Plugin version 0.11+, a separation was introduced between Package Name (in the manifest) and Application ID (in build.gradle). Application ID is the actual application identifier for the system and Google Play. Package Name in the manifest is used for resource resolution and R-class generation. It is recommended to keep them the same for simplicity.

// build.gradle (Module: app)
android {
    defaultConfig {
        applicationId "com.example.myapplication"
        minSdkVersion 24
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        debug {
            applicationIdSuffix ".debug"
        }
    }
}

The applicationIdSuffix field allows adding a suffix to the Application ID for different build configurations. A debug version can have the identifier com.example.app.debug, allowing it to be installed alongside the production version for parallel testing.

Package Name Naming Rules

Google Play sets strict rules for Package Name that must be followed when publishing. The identifier must be unique across the entire store, comply with syntax requirements, and not violate trademark policies.

Syntax Requirements

Package Name can only contain Latin letters (A-Z, a-z), digits (0-9), a dot (.), and the underscore character (_). Maximum length is 150 characters. Each segment between dots must start with a letter. Hyphens, spaces, and special characters are prohibited by Google Play rules.

Uniqueness Requirements

Uniqueness of Package Name is an absolute requirement of Google Play Store. If another application already uses the selected identifier, publication will be rejected. Google does not release identifiers of deleted applications, so choosing the first Package Name is a critical decision for every developer.

Reverse Domain Notation and Conventions

Reverse domain notation is a naming standard where the company domain name is written in reverse order: com.example instead of example.com. This system guarantees global uniqueness of identifiers because every domain name is inherently unique.

Standard Prefixes

Developers typically use a prefix corresponding to their domain’s TLD: com for commercial organizations, org for non-profits, io for technology projects, net for network services and solutions. For personal projects, com.github.username or com.email is acceptable.

• com.company.app — standard format for commercial applications
• org.company.app — for non-profit and open-source projects
• io.company.app — popular among startups and SaaS products
• com.github.username — for personal projects on GitHub

Conventions for Multiplatform Projects

For applications released on iOS and Android, it is recommended to use the same identifier on both platforms. This simplifies integration with Firebase, AppsFlyer, Adjust, and other analytics systems that bind to the project identifier. For example, com.mycompany.myapp will be the Bundle ID on iOS and Package Name on Android.

Configuring Package Name in Android Project

Configuring Package Name in an Android project involves changing the applicationId in build.gradle and the corresponding Java/Kotlin source code directory structure. Android Studio provides tools for Package Name refactoring, but for complex projects, step-by-step migration is recommended.

Directory Structure and Package Name

// File path corresponds to Package Name
// com/example/myapp/MainActivity.kt

package com.example.myapp

import android.os.Bundle
import androidx.activity.ComponentActivity

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    }
}

In Kotlin and Java, the Package Name in source files must match the directory structure. When changing the Package Name in build.gradle, you need to move files to the corresponding directories and update all package and import declarations. Android Studio can do this automatically via Refactor -> Move, but for large projects with dozens of files, it is recommended to verify the result after refactoring.

If the project uses Data Binding, View Binding or Hilt, changing the Package Name will also affect generated classes. Binding classes are created based on the module’s Package Name and layout directory. After changing the identifier, you will need to rebuild the project to update all generated references. It is recommended to perform a clean build after changing the Package Name to avoid errors from cached old references.

In Gradle 7.0+, support for namespace in build.gradle was introduced, which replaced the package field in AndroidManifest.xml for R-class and resource generation purposes. Meanwhile, applicationId remains the actual application identifier for the system and Google Play. This allows different applicationId and namespace, which is useful for library modules where the namespace is fixed while the public identifier can change during build.

For projects with modular architecture, changing the Package Name of one module can affect imports in other modules. If the data module has the package com.example.data and the domain module uses its classes, after changing the identifier, update the imports in all dependent modules. Android Gradle Plugin version 8.0+ simplifies this process with automatic namespace generation from build.gradle.

Checking Package Name Through Code

To get the current Application ID, use the BuildConfig class: BuildConfig.APPLICATION_ID. This is convenient for conditional logic in code, environment binding, or displaying the identifier in debug screens. BuildConfig is generated automatically based on build.gradle.

// Getting Application ID at runtime
val packageName = BuildConfig.APPLICATION_ID
val packageManager = packageManager
val appInfo = packageManager.getPackageInfo(packageName, 0)

println("App version: ${appInfo.versionName} (${appInfo.versionCode})")
println("Package: $packageName")

Changing Package Name After Publication

Changing Package Name after publishing an application on Google Play is an operation that means creating an entirely new product. The system does not allow updating an existing application with a different Package Name, so deciding to change the identifier is equivalent to restarting the project in the store.

Consequences of Changing Package Name

When changing Package Name, the following are lost: all ratings and reviews, installation statistics, Google Services integration (if not migrated), Firebase project links (requires creating a new google-services.json). Users will not receive an automatic update — they will see the new application in the store.

• Ratings and reviews — remain with the old application, not transferred
• Installation statistics — reset for the new Package Name
• Firebase projects — require a new google-services.json configuration and reconfiguration of all services
• Users — do not receive automatic updates, need to be notified separately

When Changing Package Name is Justified

Changing Package Name may be justified during company rebranding, transferring an application to a different developer account, or creating a separate version for another region. In any case, before changing, it is recommended to notify users through the old application and prepare a migration plan with data transfer. Without a migration plan, users will lose access to purchased content, subscriptions, and saved application data. Migration includes transferring the database and files via SharedPreferences or Room.

Before changing the Package Name, make sure the new identifier is unique and complies with naming rules. Create a new application in Google Play with the new Package Name and publish it as a separate product. In the old application description, provide a link to the new one. Consider using Google Play Custom Store Listing to redirect users.