An Android version code is a positive integer that tells Android and Google Play which build of your app is newer. Increase it every time you ship a build that should replace an installed one: each Play upload and each APK update you hand to testers. It is not the version number users see; that is the version name.
What an Android version code is
The Android version code is an internal number, versionCode, that the system compares between builds. Android’s Version your app guide defines it as “a positive integer used as an internal version number,” where higher numbers mean more recent versions.
You set it in the defaultConfig block of your module’s Gradle file, next to the version name. The build merges both into the app’s manifest. A new project usually starts with this:
defaultConfig {
versionCode = 1
versionName = "1.0"
}Version code vs version name
The version code is for machines and the version name is for people. Android’s guide calls versionName “a string used as the version number shown to users,” while the code stays hidden.
| Version code | Version name | |
|---|---|---|
| Type | Positive integer | Any string |
| Who sees it | Android and Google Play | Users, on the store and in settings |
| Must it increase? | Yes, for every update | No, it’s up to you |
| Example | 1 |
"1.0" |
The two don’t have to match. You can ship several builds that all show version name “1.0” while the version code rises each time. Android’s docs say apps and publishing services shouldn’t show the version code to users at all.
When do you increase the version code?
Increase the version code for every release, big or small. Android’s guide says the usual pattern is to release the first version with versionCode set to 1, then increase it with each release, “regardless of whether the release constitutes a major or minor release.”
Two rules force this:
- Google Play rejects reused numbers. Android’s docs say you can’t upload an APK “with a versionCode you have already used for a previous version.” Play’s update rules also require the version code to be greater than the current version.
- Phones block downgrades. Android prevents users from installing an APK with a lower version code than the one already installed.
Which changes need a new build at all
You only bump the version code when you build a new package. For a WebView app, plenty of changes reach users with no new build, so the counter stays where it is.
| Change | New build and higher version code? |
|---|---|
| Edit pages on your live website | No, the app loads them from the web |
| Change the app name or icon | Yes |
| Change navigation, colours or theme | Yes |
| Edit bundled HTML or text pages | Yes |
| Rebuild the same project with no changes | Only if you upload or install it as an update |
This matches how Web2Apk works: live website content can change without an app update, while the app name, icon, navigation and bundled HTML change only with a new build. That is the biggest advantage of a website-based app. Most content fixes ship the moment you publish them on the site, with no review queue and no version bump.
The errors you see when the version code is wrong
A wrong version code shows up as a clear upload error or a failed install. The Play Console message is usually:
Version code 1 has already been used. Try another version code.
That error, discussed in this Microsoft Q&A thread, means Play already received a build with that number. Raise the code and rebuild.
On a phone, installing a lower version code over a higher one fails. Often you’ll just see the generic App not installed error. For testing on your own device, adb install has a -d option that Android’s adb docs describe as “Allow version code downgrade.” Don’t rely on that for real users.
How to set the version code in common tools
Every Android build tool exposes the same number under a different name. Find it, raise it, rebuild.
- Android Studio (Gradle): change
versionCodeindefaultConfig. - Flutter: the number after the
+inpubspec.yaml’sversion. The Flutter release docs say the build number becomesversionCode, and you can override it with--build-number. - Web2Apk: the builder tracks the version code for you, per package name, and offers a minimum version code setting.
After building, check the new number before uploading. Then check that the package name hasn’t changed, because a higher version code only helps if it’s the same app.
How high can a version code go?
Google Play accepts version codes up to 2100000000. You’ll never reach it by adding 1 per release, but schemes that pack dates or build numbers into the code can.
Some teams skip numbers on purpose. Android’s docs mention that apps publishing multiple APKs can use pre-set version code ranges per APK. Skipping is fine; going backward isn’t.
How Web2Apk keeps version codes in order
Web2Apk tracks version codes per package name in your browser, from 1 up to 2,100,000,000. Our signing and updates guide explains that a normal update keeps the same package name and signing key and uses a higher version code.
The limitation is that the counter lives in one browser. If you switch devices or clear browser data without a current backup, the builder doesn’t know your last released number. Exported project backups carry the version counter with them. Without one, set the minimum version code above the last build you shipped before generating an update.
The same goes for any other tool: write down the last version code you released. If you also lose your signing key, see what to do when you lose your signing key. If your first Play release is still ahead of you, read about Google Play’s tester rule for new accounts before you start counting builds.
FAQ
Do I need to increase the version code for a small bug fix?
Yes. Android’s docs say to increase the version code with each release, whether it is major or minor. Play won’t accept a version code you already used.
Does the version code have to go up by exactly 1?
No. It only has to be higher than the version users have. Most developers add 1 per release, but skipping numbers is allowed up to Google Play’s limit of 2100000000.
Is the version code the same as the version name?
No. The version name is the string users see, such as 1.0. The version code is an internal number Android and Google Play use to compare builds.
Can I go back to a lower version code?
Not for normal users. Android blocks installing a lower version code over a higher one. During development, adb install -d allows a version code downgrade.