APK Version Code vs Version Name: What Each Value Controls

APK version code vs version name comes down to two different jobs: versionCode tells Android and app stores which build is newer, while versionName gives users a readable release label such as 2.4.1.

A higher versionCode controls update ordering. The versionName can follow semantic versioning, include words such as beta, or even remain unchanged between builds. Android does not compare version names to decide whether one APK can update another.

Detail	versionCode	versionName
Data type	Positive integer	String
Main audience	Android and distribution platforms	App users
Typical value	42	"2.4.1"
Must increase for a new Google Play release	Yes	No
Must increase by exactly one	No	No
Used to determine which build is newer	Yes	No
Normally visible to users	No	Yes
Can contain dots, letters, or labels	No	Yes
Maximum accepted by Google Play	2100000000	No equivalent numeric limit

What Is an APK Version Code?

The APK version code is a positive integer stored as versionCode. Android uses it to compare builds belonging to the same application.

If an installed app has versionCode 41 and a replacement APK has versionCode 42, Android treats the replacement as newer. If the replacement has code 40, a normal installation is treated as a downgrade and is blocked.

A simple release history may look like this:

Release	versionCode	versionName
Initial release	1	1.0.0
Bug fix	2	1.0.1
Feature update	3	1.1.0
Urgent rebuild	4	1.1.0

The fourth build can keep the same visible name while using a higher internal code. Android recognizes it as a newer build because it compares versionCode, not versionName.

The Code Does Not Need to Increase by One

Every later release needs a greater code, but the difference does not have to be one. A project can move from 100 to 110, 200, or another higher integer.

Sequential values are usually easiest to manage:

101

102

103

104

Larger gaps may be useful when a team reserves ranges for product variants or separate build pipelines. Whatever system is chosen must prevent duplicates and preserve increasing order.

Google Play Does Not Allow Reused Version Codes

A code already used for an app cannot be uploaded again as a new Google Play release. Changing only the version name does not make the upload unique.

For example:

Existing release:

versionCode = 25

versionName = "3.1.0"

Rejected replacement:

versionCode = 25

versionName = "3.1.1"

The second package still uses code 25. It needs a new value greater than the relevant existing release, such as 26.

Google Play accepts version codes up to 2100000000. A numbering scheme should leave enough room for the app’s expected lifetime, build variants, and automated releases.

What Is an APK Version Name?

The APK version name is the user-facing release identifier stored as versionName. Values commonly look like:

1.0

2.3.7

5.0-beta

2026.09

4.2 Enterprise

Because it is a string, it is not limited to a sequence of integers. Teams normally choose a predictable format so users, support staff, testers, and release notes refer to the same build clearly.

A common structure is:

MAJOR.MINOR.PATCH

Under that convention:

• 3.0.0 may represent a major product change.
• 3.1.0 may add backward-compatible features.
• 3.1.1 may contain fixes.

Android does not require semantic versioning. It is an editorial and release-management choice rather than an update-order rule.

Which Value Actually Triggers an Android Update?

The version code determines whether a build is newer, but a valid app update requires more than a higher number. The replacement package must also belong to the same application and satisfy Android’s signing requirements.

A normal update requires:

• The same application ID or package identity
• A compatible signing identity
• A higher versionCode
• Compatibility with the device and installed Android version

A higher code cannot turn an unrelated package into an update. Likewise, changing the version name alone cannot make an old build newer.

Consider this example:

Installed build	New build	Result
Code 12, name 1.8	Code 13, name 1.9	Recognized as newer
Code 12, name 1.8	Code 12, name 2.0	Not a new version by code
Code 12, name 1.8	Code 11, name 3.0	Treated as a downgrade
Code 12, name 1.8	Code 13, name 1.7	Newer internally, confusing publicly

The final case is technically possible: code 13 is newer even though the visible name appears older. It should normally be corrected because it can confuse users, testers, support teams, and release records.

Can the Version Name Stay the Same?

Yes. Two published builds may use the same versionName as long as the later release has a new, higher versionCode.

This can happen when a developer rebuilds an app to correct packaging, signing configuration, or distribution-specific behavior without presenting it as a separate product release. For example:

First build:

versionCode = 87

versionName = "4.6.0"

Replacement build:

versionCode = 88

versionName = "4.6.0"

The second package is newer to Android. Both appear as version 4.6.0 to users, however, which makes support and bug reporting harder. Giving every distributed build an identifiable public label is often more practical, even though Android does not require it.

What Happens If the Version Name Goes Backward?

Suppose an installed app uses:

versionCode = 30

versionName = "2.5.0"

The next release accidentally contains:

versionCode = 31

versionName = "2.4.9"

Android considers code 31 newer. The lower-looking version name does not reverse the internal ordering.

The release may still create problems:

• Users may think they received an older app.
• Support teams may misidentify reported builds.
• Store listings and release notes may appear inconsistent.
• Analytics grouped by visible version may become harder to interpret.

If the package has not been distributed, correct the name before release. If it is already live, the appropriate response depends on the release process, but the next package must still use another higher code. Code 31 cannot simply be reused.

How to Roll Back an Android Release Safely

Publishing an old APK with its original lower code is not a valid rollback for users who already installed the newer release. Android sees it as a downgrade.

A safer rollback is to rebuild the last known good source while assigning it a version code higher than the faulty release.

Stable release:

versionCode = 70

versionName = "5.2.0"

Faulty release:

versionCode = 71

versionName = "5.3.0"

Rollback build based on stable code:

versionCode = 72

versionName = "5.3.1"

Code 72 allows affected devices to move forward internally while the app’s functional changes return to the stable implementation. The visible name and release notes should make the nature of the corrective release clear.

Where to Set versionCode and versionName

Modern Android projects normally define both values in the application module’s Gradle build file.

Kotlin DSL: build.gradle.kts

android {

    defaultConfig {

        applicationId = "com.example.myapp"

        versionCode = 42

        versionName = "2.4.1"

    }

}

Groovy DSL: build.gradle

android {

    defaultConfig {

        applicationId "com.example.myapp"

        versionCode 42

        versionName "2.4.1"

    }

}

These values are merged into the application manifest during the build. If version information also appears directly in the source manifest, values supplied by the Gradle build configuration take precedence. Keeping the release values in Gradle avoids uncertainty during manifest merging.

Product flavors and build variants can override the defaults. Teams using overrides should inspect the final release artifact rather than assuming it inherited the intended values.

How App Bundles and Split APKs Handle Versions

For an Android App Bundle, the base module supplies the app’s versionCode and versionName. Google Play uses that information when generating optimized APKs for individual devices.

The split APKs generated from one bundle share the bundle’s version code. They are components of one installed app version, not independent releases that each need a public version name.

This differs from older workflows in which developers manually uploaded several standalone APKs for different device configurations. In that model, each published APK needed an appropriate unique version code, and code ordering affected which compatible APK a device received.

For most current App Bundle workflows, one release-level code in the base module is the relevant value.

How to Check the Values Inside an APK

Do not rely only on an APK filename. A file named app-5.0.apk can contain a completely different version name or code.

Android SDK’s APK Analyzer can display the values stored in the package:

apkanalyzer apk summary app-release.apk

Typical output follows this pattern:

com.example.myapp 42 2.4.1

The three fields are the application ID, version code, and version name.

Either value can also be requested separately:

apkanalyzer manifest version-code app-release.apk

apkanalyzer manifest version-name app-release.apk

For an app already installed on a connected device, its package details can be inspected with ADB:

adb shell dumpsys package com.example.myapp

The output contains versionCode and versionName, along with other package information. Replace com.example.myapp with the actual application ID.

An ordinary user can usually see the version name on the app-information screen in Android settings. Device manufacturers may place it in different locations, and that screen normally does not expose the internal code clearly.

Version Numbers Do Not Prove an APK Is Authentic

Two APK files can display the same application name, version name, and version code while containing different code. Version metadata identifies a release; it does not establish who created the file or whether it was altered.

The signing certificate is the more important identity signal. Anyone evaluating an APK obtained outside its normal distribution channel should verify the APK signature before installing and compare the signing identity with information obtained independently from the legitimate publisher.

A file hash answers another question: whether two files are byte-for-byte identical. Neither a familiar filename nor a believable version label is a substitute for those checks.

A Reliable Versioning Strategy

A straightforward system works well for most Android projects:

1. Treat versionCode as an independent, monotonically increasing build identifier.
2. Treat versionName as a clear release label for users and support teams.
3. Generate or reserve version codes centrally so parallel builds cannot collide.
4. Never derive update ordering by comparing version-name strings.
5. Inspect the completed APK or App Bundle before uploading it.
6. Coordinate codes across production, testing, and other distribution tracks.
7. Rebuild a rollback with a new higher code instead of republishing an older package unchanged.
8. Keep release notes tied to both the visible name and the internal code.

Encoding the complete semantic version into the code can work, but it adds limits and collision risks. A simple increasing build sequence is usually easier unless multiple APK variants require a carefully designed range system.

Common Versioning Mistakes

Changing Only versionName

A new public label does not create a valid new Play release when the version code has already been used.

Decreasing versionCode During a Rollback

Devices with the later build normally reject the lower-code APK as a downgrade.

Assuming versionName Controls Update Order

Android compares integer version codes, not dotted names such as 2.9.9 and 2.10.0.

Reusing Codes Across Build Pipelines

Two branches or automated jobs can generate the same code unless allocation is centralized.

Trusting the Gradle Source Without Inspecting the Artifact

Flavors, build types, environment variables, and automation can override defaults. The final package is the authoritative output to inspect.

Confusing App Version With Android Version

versionCode and versionName describe the application release. They are different from minSdk, targetSdk, Android OS version numbers, and API levels.

Frequently Asked Questions

Is versionCode visible to users?

It is primarily internal metadata used by Android and distribution services. Apps may expose it through a custom diagnostic screen, but the normal public release label is versionName.

Must versionCode match versionName?

No. Code 142 can use the name 3.8.0. There is no required mathematical relationship between them.

Can versionCode skip numbers?

Yes. A release can move from 100 to 105 as long as the new value is greater and has not already been used where uniqueness is required.

Can two releases have the same versionName?

Yes. The later release still needs a higher version code. Repeating the visible name is technically possible but may make support and analytics less clear.

Does changing versionCode change app features?

No. It changes version metadata. Features change only when the app’s code, resources, configuration, or delivered content changes.

Why does Android reject an older APK?

If the package matches an installed app but carries a lower version code, Android normally treats the installation as a prohibited downgrade. A certificate mismatch or incompatible package configuration can also prevent installation.

Which value should appear in release notes?

Use the user-facing version name, and record the version code internally for exact build identification.

Final Thoughts

APK version code vs version name is a separation between technical ordering and public communication. versionCode must move upward so Android and Google Play can identify a later release. versionName explains that release to users in a readable form.

Reliable Android versioning keeps the values independent but coordinated: a unique increasing code for every distributed build, a clear public name, and an inspection step that confirms the final package contains exactly what the release process intended.