Version Code: What It Is, Numeric Identifier and Updates

What Is Version Code in Android

Version Code is an integer of type Integer that is assigned to each build of an Android application. Unlike Version Name, Version Code is not displayed to users and is used exclusively by the operating system and Google Play to compare versions when installing updates.

Version Code Format

Version Code must be a positive integer in the range from 1 to 2100000000. Each subsequent build must have a Version Code strictly greater than the previous one. If a developer released a build with Version Code 5, the next publication can use 6, 7, or any number greater than 5, but not 4 and not 5 again.

History of Origin

Google introduced the separation of Version Code and Version Name with the release of the Android SDK in 2007. Version Code was conceived as a machine identifier for automatic version comparison, while Version Name was meant as a human-readable label. This separation allows the developer to name the version however they wish while maintaining a strict update order through the numeric code.

How Versioning Works Through Version Code

Comparison mechanism of Version Code is built into the Android operating system and Google Play store. With each publication, Google Play checks that the Version Code of the new build is greater than the code of the installed version. If the condition is not met, the publication is rejected with an error.

Update Check Process

When a device contacts Google Play to check for updates, the server compares the Version Code of the installed application with the maximum available in the store. If the code on the server is greater, the download and installation of the update starts. The user sees the Version Name specified by the developer, but the update decision is made based on the Version Code.

Version Code Increment

Developers use different strategies for incrementing Version Code. The simplest is increasing by 1 with each build. For CI/CD pipelines, a timestamp or build number is often used: 2026070301 (year-month-day-number). It is important that the code increases monotonically and does not repeat between different builds and Google Play tracks.

• Monotonous increment — increase by 1 with each commit to the release branch
• Timestamp format — 20260703 for daily builds, 2026070301 for multiple builds per day
• SemVer in numbers — 100010000 for version 1.1.0 (major 1, minor 1, patch 0)
• Build number — using BUILD_NUMBER from the CI system (Jenkins, GitHub Actions)

Differences Between Version Code and Version Name

Version Code and Version Name are two independent fields in build.gradle that perform different functions. Version Code is an internal identifier for the system, Version Name is a marketing label for the user. They can change independently of each other.

Version Name for the User

Version Name is a string that is displayed in the application settings, in Google Play, and in update dialogs. The developer can specify any format: 1.0.0, 2.3.1-beta, 3.0-rc1. Version Name is not used for comparing string versions — Google Play always relies on Version Code.

Divergence Scenarios

A situation is possible where Version Code increases while Version Name stays the same. For example, if a developer fixes a critical bug in a hotfix build without changing functionality. Version Name remains 2.0.0, while Version Code changes from 5 to 6. Google Play will correctly handle such an update.

// Example: version name does not change, code increases
android {
    defaultConfig {
        versionCode 6  // Was 5 — hotfix without new features
        versionName "2.0.0"  // Not changed
    }
}

// Checking versions at runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code: $code, Name: $name")

Configuring Version Code in build.gradle

Configuring Version Code is done in the build.gradle file of the application module. The versionCode field accepts an integer and is part of the defaultConfig block. For different flavor builds, you can set custom values through the versionCode field in the product configuration.

Basic Configuration

// build.gradle.kts — Kotlin DSL
android {
    defaultConfig {
        applicationId "com.example.app"
        versionCode 15
        versionName "2.1.0"
    }

    flavorDimensions +"version"
    productFlavors {
        create("demo") {
            versionCode 1015
        }
        create("full") {
            versionCode 2015
        }
    }
}

Product flavors allow using different Version Code values for various configurations: demo version, separate version for tablets. If flavors are used in the project, the final Version Code is composed of the base number and the flavor-specific increment. Google Play tracks each combination independently.

Automation of Increment via CI

In CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins), Version Code is often generated automatically based on the build number or date. This eliminates human error during manual updates. The script reads the current Version Code from build.gradle, increments it, and writes it back before starting the build.

// Automatic Version Code increment
import java.util.Properties
import java.io.FileInputStream

val versionProps = Properties()
versionProps.load(FileInputStream("version.properties"))

val versionCode = versionProps.getProperty("VERSION_CODE").toInt() + 1
versionProps.setProperty("VERSION_CODE", versionCode.toString())

android {
    defaultConfig {
        versionCode = versionCode
    }
}

Version Code Specifics for Publishing on Google Play

Google Play has strict rules for Version Code when publishing and updating applications. Violating these rules leads to build rejection or the inability to release an update. The developer needs to understand the limitations and code management strategies at all stages of the lifecycle.

Monotonous Increment Rule

Google Play does not allow uploading an APK or AAB whose Version Code is less than or equal to the currently published one. This rule applies to each track (production, beta, alpha) independently. If a build with Version Code 10 is uploaded to production and a build with code 5 is in alpha, the alpha track can be updated to 6, 7, 8, or 9, but production stays at 10.

Track Migration

When promoting a build from alpha to beta and then to production, Version Code must increase at each stage. If the alpha version has code 10, beta can use 11, and production — 12. You cannot roll out a build with code 10 to production if alpha is already using 10, even if production has not seen it yet.

• Monotonous increment — each build in a track has a Version Code greater than the previous one in the same track
• Cross-track awareness — when promoting between tracks, Version Code increases sequentially
• Internal testing — the internal test track uses the same monotonicity rules
• Multiple APKs — the old publishing format required a unique Version Code for each APK

Version Code Errors

The most common error is a Version Code match in different builds uploaded to the same track. Google Play returns the APK_VERSION_CODE_ALREADY_EXISTS error. Another error is exceeding the maximum value of 2100000000, which causes a compilation failure. To avoid conflicts, use automatic code generation in your CI system tied to the build number or build date.

Developers also often make the mistake of not incrementing Version Code when building a hotfix release for an alternative track. If production has code 15 and the alpha track stayed at 14, when promoting alpha to production, Google Play will reject the build because its code is less than the current production code. Monitor the monotonicity of the code across all tracks simultaneously — for this, it is convenient to use a single version.properties file from which all tracks read the current value.