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.
Page Contents
Android: two numbers
| Field | Type | Shown to users? | Rules |
|---|---|---|---|
| versionCode | Integer | No | Must be higher than every previous upload; maximum 2,100,000,000 |
| versionName | Text | Yes | Any 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
| Field | Info.plist key | Shown to users? | Rules |
|---|---|---|---|
| Version | CFBundleShortVersionString | Yes | Up to three numbers, like 2.4.1 |
| Build | CFBundleVersion | No | Must 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
versionCodeand 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.
Need help building or publishing your app? Talk to Techpass Master – we design, build and publish Android apps for clients worldwide.
