How to Use Gradle Flavors in Android to Build Multiple App Versions from One Codebase

Ever wondered how big apps manage free vs paid versions, or white-label multiple client apps from a single Android project? The answer is Gradle Flavors.

Imagine you're building an app for a fitness startup. The client loves it. Then they say: "Can we also get a version for our premium users, with extra features and no ads? Oh, and one more version for our corporate partners?"

You smile, and quietly panic.

Do you:

• Copy the codebase three times?
• Manually toggle features before every build?
• Cry?

Nope. You use Gradle Flavors.

What Are Gradle Flavors?

Flavors are like the "personalities" of your app. Each flavor can have its own configuration, resources, and even features, all while sharing the same codebase.

You define flavors inside your build.gradle file. From there, Gradle handles the rest: building separate APKs or app bundles with your desired changes.

Why Use Flavors?

Gradle Flavors aren't just a fancy build trick. They are your secret weapon when one app needs to wear many hats. Whether you're serving different user tiers, clients, or regions, flavors let you adapt your app without copy-pasting your codebase into chaos.

Let us see some use cases in real world:

• Free vs Paid Versions: Show ads and limit features in the free version. Unlock everything and go ad-free in paid. All from the same project.
• White-labeling: Have three clients? Give each their own logo, color scheme, and name, without breaking your app's core.
• Internal Builds for QA or Stakeholders: Add dev-only menus, debug logs, or testing tools - features regular users will never see.

And best of all? You don't duplicate code.

One App, Many Audience

Remember that fitness app you built for the startup? Now it needs to exist in three versions:

• A basic version for regular users
• A premium version with advanced tracking and no ads
• And a corporate version tailored for enterprise wellness programs

Sounds like a lot, right? But with Gradle Flavors, it's surprisingly simple. You don't need three projects. You just define three "personalities" of the same app, each with its own branding, features, and config, all neatly handled in a single codebase.

Here's how you'd set that up in your build.gradle file:

android {
    ...
    productFlavors {
        free {
            dimension "access"
            applicationId "com.fitmaster.free"
            versionCode 1
            versionName "1.0"
            // Define flavor-specific configurations
            buildConfigField "boolean", "IS_PREMIUM", "false"
        }
        premium {
            dimension "access"
            applicationId "com.fitmaster.premium"
            versionCode 1
            versionName "1.0"
            // Define flavor-specific configurations
            buildConfigField "boolean", "IS_PREMIUM", "true"
        }
    }
    buildTypes {
        debug {
            // Debug - specific configurations
            ...
        }
        release {
            // Release - specific configurations
            ...
        }
    }
    ...
}

With just these few lines of configuration, you've created two distinct versions of your app - Free and Premium, all while sharing a single codebase. No messy duplication. No last-minute toggling.

And the best part? You're not limited to just two.

Need a third flavor for corporate partners with custom branding, features, or even a different API base URL?

Easy. Just add a corporate flavor the same way, and you're good to go.

In the example above, we've defined two product flavors: free and premium. Each one comes with its own unique applicationId, which means they install as separate apps - a lifesaver when you're juggling multiple builds on the same device.

Now here's where the magic begins: you can tailor each flavor's behavior. Want to hide premium workouts in the free version? Or maybe give the premium build a slick new app icon or splash screen? All possible, without touching your core codebase.

We also defined two buildTypes: debug and release.

• Debug is your playground - full of logs, testing tools, and whatever else makes development easy.
• Release is the polished version - optimized, signed, and ready for the app store.

Once you've got your flavors and build types in place, Gradle automatically generates the following build variants:

• freeDebug
• freeRelease
• premiumDebug
• premiumRelease

Each of these variants is a unique version of your app. For example, you can build premiumRelease to create the signed APK your paying users will install. Or test new updates in the freeDebug version without touching the live app.

No duplicate code. No messy toggling. Just clean, efficient builds tailored for every scenario.

Structuring Your Project for Flavors

Alright, now that we've set up our flavors and build types, let's talk about how your project structure actually looks when you're working with Gradle flavors. Spoiler: it's super organized, and you're going to love it.

app/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── fitness/
│   │   │               ├── MainActivity.java
│   │   │               └── ...
│   │   └── res/
│   │       ├── layout/
│   │       ├── drawable/
│   │       ├── values/
│   │       └── ...
│   ├── free/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── fitness/
│   │   │               ├── MainActivity.java
│   │   │               └── ...
│   │   └── res/
│   │       ├── layout/
│   │       ├── drawable/
│   │       ├── values/
│   │       └── ...
│   └── premium/
│       ├── java/
│       │   └── com/
│       │       └── example/
│       │           └── fitness/
│       │               ├── MainActivity.java
│       │               └── ...
│       └── res/
│           ├── layout/
│           ├── drawable/
│           ├── values/
│           └── ...

Let me break this down like I would to a teammate who's new to Gradle flavors:

• app: Your main module. All your build logic and source files live here.
• src: Where you organize your code based on flavors and build types.

Inside src, you'll see:

• main: This is your foundation. It holds all the shared code and resources. Think of it as your app's core - logic, layouts, assets, all the things that don't change between flavors.
• free: This is flavor-specific. You want to show ads only in the free version? Customize the splash screen? Add a "Get Premium" button? This is where you do it.
• premium: This one's for your premium users. Maybe it has exclusive features, no ads, or different branding. Any code or resources placed here will override what's in main when you build the pro version.

The same structure goes for Java/Kotlin code and resources (like layouts, drawables, or strings). If a file exists in both main and a flavor-specific folder, the flavor version takes precedence when building.

That's the beauty of Gradle Flavors. It scales with your needs. Whether it's two builds or ten, each variant gets its own personality without sacrificing your development sanity.

You write once. Gradle builds the rest.

Wrapping It Up: One Codebase, Many Faces

Think of Gradle Flavors as your app's shape-shifter. One project, one team, one codebase, but multiple identities. Whether you're building for free users, premium subscribers, corporate clients, or internal testers, flavors give you a clean, scalable way to deliver exactly what each group needs, without losing your mind.

And the best part? You didn't duplicate a single file. You didn't fork your project into chaos. You simply told Gradle, "Here's what I want," and it built your app like a pro.

So the next time someone asks,

• "Can we make one version for our partner brand?"
• "What if we add a beta build just for QA?"
• "Can we launch a separate app for UAE with different payment APIs?"

You don't flinch.

You open your build.gradle, add a flavor, and carry on like the build wizard you are.

Because now? You've got flavors in your toolkit, and there's no going back.