Introduction

versionCode and versionName describe two different aspects of Android app versioning. versionCode is the monotonically increasing internal version used for update ordering, while versionName is the user-visible version string shown to humans.

The Conceptual Difference

versionCode answers this question:

• is build B newer than build A from the platform's point of view?

versionName answers this question:

• what version label should the user or support team see?

So a typical release might have:

• 'versionCode = 42'
• 'versionName = "2.3.1"'

Users care about 2.3.1. The Android ecosystem cares that 42 is greater than the previous code.

What versionCode Is For

versionCode is an integer that must increase for each release you want the platform and app stores to treat as newer.

A minimal modern configuration in Gradle Kotlin DSL looks like this:

1android {
2    defaultConfig {
3        versionCode = 42
4        versionName = "2.3.1"
5    }
6}

If you upload a new build with a lower or unchanged versionCode, it will not be treated as a newer release in the normal Android distribution workflow.

This makes versionCode operationally important even though users rarely see it directly.

What versionName Is For

versionName is a string displayed to users, testers, and support staff.

Examples:

• '1.0'
• '2.3.1'
• '2026.03'
• '5.0-beta2'

Unlike versionCode, the platform does not use versionName as the authoritative ordering rule for updates. It is a label, not the internal numeric precedence signal.

That means you are free to choose a naming scheme that fits your release process, as long as it is meaningful to humans.

Why The Manifest Wording Is Historically Confusing

Older Android discussions often describe these values as AndroidManifest.xml attributes. Historically that was how many developers encountered them conceptually.

In modern Android builds, you usually set them in the module build configuration rather than editing the manifest directly by hand. The build system then packages the resulting values into the app manifest metadata.

So the concepts still exist, but the normal authoring location is your Gradle configuration.

A Practical Versioning Pattern

A straightforward release pattern is:

• increase versionCode every release
• update versionName only when the user-facing version label changes according to your scheme

For example:

1android {
2    defaultConfig {
3        versionCode = 105
4        versionName = "3.4.0"
5    }
6}

The next hotfix might become:

1android {
2    defaultConfig {
3        versionCode = 106
4        versionName = "3.4.1"
5    }
6}

The specific numbering scheme is flexible. The non-negotiable rule is that the internal code must keep moving upward for newer releases.

Why You Need Both

If you only had a user-facing string, the platform would need to guess ordering from arbitrary text. That becomes messy quickly.

If you only had an internal integer, users and testers would not have a friendly semantic version to discuss.

Keeping both fields separate solves both problems cleanly:

• machines get a simple monotonic integer
• humans get a readable version label

Build Variants And Automation

In more advanced builds, teams often derive version values automatically from CI pipelines, Git tags, or flavor-specific logic.

For example, you might keep a stable versionName base but append a suffix for internal builds, or derive versionCode from a build number.

Whatever automation you use, the rules stay the same:

• 'versionCode must be monotonic for releasable builds'
• 'versionName should communicate clearly to humans'

Automation changes how the values are produced, not what they mean.

Common Pitfalls

• Treating versionName as if it controlled upgrade ordering.
• Forgetting to increment versionCode for a new release.
• Thinking these values must still be edited manually in the manifest in modern Android projects.
• Using a version naming scheme that is readable to machines but confusing to humans.
• Letting build automation generate inconsistent version pairs across variants.

Summary

• 'versionCode is the internal monotonically increasing release number.'
• 'versionName is the human-readable version label.'
• Modern Android projects usually define both in Gradle, not by hand in the manifest.
• The update system cares about versionCode; users care about versionName.
• Keep versionCode increasing and versionName meaningful.