How to change the Android app package name when assembling with Gradle?

As a simpler alternative to using product flavours as in Ethan's answer, you can also customise build types.

How to choose between the approaches:

• If you need different package names to be able to have both debug and release apks installed on a device, then use the build type approach below, as Gradle plugin docs agree. In this case flavours are an overkill. (I think all projects should by default do this, as it will make life easier especially after you've published to the store and are developing new features.)
• There are valid uses for product flavours, the typical example being an app with free and paid versions. In such case, check Ethan's answer and read the documentation too: Configuring Gradle Builds and Gradle Plugin User Guide.

(You can also combine the two approaches, which results in every build variant having distinct package name.)

Build type configuration

For debug build type, and all other non-release types, define applicationIdSuffix which will be added to the default package name. (Prior to Android Gradle plugin version 0.11 this setting was known as packageNameSuffix.)

android {
    buildTypes {
        debug {
            applicationIdSuffix '.debug'
            versionNameSuffix '-DEBUG'
        }

        beta {
            applicationIdSuffix '.beta'
            versionNameSuffix '-BETA'

            // NB: If you want to use the default debug key for a (non-debug) 
            // build type, you need to specify it:
            signingConfig signingConfigs.debug 
        }

        release {
            // signingConfig signingConfigs.release
            // runProguard true
            // ...
        }

    }
}

Above, debug and release are default build types whose some aspects are configured, while beta is a completely custom build type. To build the different types, use assembleDebug, assembleBeta, etc, as usual.

Similarly, you can use versionNameSuffix to override the default version name from AndroidManifest (which I find very useful!). E.g. "0.8" → "0.8-BETA", as configured above.

Resources:

• This example is straight from Xavier Ducrohet's "Google I/O 2013: The New Android SDK Build System" presentation.
• Build Types in the User Guide.

Myself I've been using productFlavors so far for this exact purpose, but it seems build type customisation may be closer to my needs, plus it keeps the build config simpler.

Update (2016): I've since used this approach in all my projects, and I think it definitely is the way to go. I also got it included in Android Best Practices guide by Futurice.

You could so something like this

android {
    ...

    defaultConfig {
        minSdkVersion 8
        versionCode 10
    }

    flavorDimensions "flavor1", "flavor2"

    productFlavors {
        flavor1 {
            applicationId "com.example.flavor1"
            versionCode 20
        }

        flavor2 {
            applicationId "com.example.flavor2"
            minSdkVersion 14
        }
    }
}

You can also change the field android.defaultConfig.applicationId if you want to do one-off builds.

Taken from: http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Product-Flavor-Configuration

With the gradle plugin version of 1.0.0+ you have to use applicationId as stated in the migration guide

Renamed Properties in ProductFlavors

packageName => applicationId

Thus in your build.gradle you would now use:

productFlavors {
   flavor1 {
      applicationId "com.example.flavor1"
   }

   flavor2 {
      applicationId "com.example.flavor2"
   } 
}