App Versioning Explained: versionCode, versionName and Semantic Versioning

Every app update needs a new version number – and both app stores reject uploads when it is wrong. Android and iOS each use two different numbers, which confuses many developers. Here is what each one means, how semantic versioning works and how to avoid the classic “version code already used” error.

Free tool
Bump your app version
Enter your current version, choose major, minor or patch and get the next versionName, versionCode and iOS build number with ready-to-paste snippets. Free.
Open Version Bumper →

Android: two numbers

FieldTypeShown to users?Rules
versionCodeIntegerNoMust be higher than every previous upload; maximum 2,100,000,000
versionNameTextYesAny string, usually like 2.4.1

Set both in build.gradle.kts inside defaultConfig. Google Play only checks versionCode – it must always increase, even for internal testing tracks.

iOS: two numbers

FieldInfo.plist keyShown to users?Rules
VersionCFBundleShortVersionStringYesUp to three numbers, like 2.4.1
BuildCFBundleVersionNoMust be unique and higher for each upload of the same version

In Xcode these are “Version” and “Build” (MARKETING_VERSION and CURRENT_PROJECT_VERSION).

Semantic versioning: MAJOR.MINOR.PATCH

  • MAJOR (3.0.0) – big redesigns or changes that break compatibility
  • MINOR (2.5.0) – new features that keep things compatible
  • PATCH (2.4.2) – bug fixes only

When you raise one number, reset the numbers to its right: 2.4.7 → 2.5.0, 2.9.3 → 3.0.0.

Strategies for versionCode

  • Simple counter: 1, 2, 3, … – easy, works for most apps.
  • Derived from versionName: major × 10000 + minor × 100 + patch, so 2.4.1 → 20401. Readable, but leave room for hotfixes.
  • CI build number: your build server’s run number – always increasing.

Pick one strategy and keep it. Our Version Bumper calculates the next values for you.

Common errors

  • “Version code X has already been used” – raise versionCode and rebuild.
  • “The bundle version must be higher than the previously uploaded version” (App Store Connect) – increase the build number.
  • Users see an old version name – you changed versionCode but forgot versionName.
  • Update not offered to users – the new versionCode is lower than the installed one.

Tips

  • Keep versions in one place – for Android, a Gradle version catalog can hold your library versions, while app versions often live in gradle.properties.
  • Tag releases in git with the version name.
  • Write release notes for every version users see.

FAQ

What is the difference between versionCode and versionName?

versionCode is an internal integer that must increase; versionName is the version users see.

What is the maximum versionCode?

2,100,000,000 on Google Play.

Can I skip version numbers?

Yes. versionCode only has to increase; it does not have to increase by one.

What is CFBundleVersion?

The iOS build number. It must be unique for each upload of the same version.

Should Android and iOS versions match?

It helps users and support teams if the visible version (2.4.1) matches on both platforms.

Free tool
Try the free Version Bumper
No signup and nothing uploaded – it runs right in your browser. Browse all 74 free tools on our Free Tools page.
Open Version Bumper →

Need help building or publishing your app? Talk to Techpass Master – we design, build and publish Android apps for clients worldwide.

WhatsApp us📞 Call now