versionCode vs versionName
versionName is a free-form string shown to users — on the Play listing, in Settings → Apps, in your About screen. Android never interprets it; "1.4.2", "2024.09" and "Sunrise" are all legal. versionCode is a positive integer, invisible to users, that the installer and Google Play compare: an update installs only if its versionCode is higher than the one already installed, and Play refuses an upload whose code is not higher than every code it has seen for that app. The maximum is 2,100,000,000.
So the name is for people and the code is for machines, and the only rule that matters is that the code goes up with every build you ship.
Three schemes that work
| Scheme | Example | Good for | Watch out for |
|---|---|---|---|
| Semantic (MMmmpp) | 1.4.2 → 10402 | Apps with real releases; the code is derivable from the name | Minor or patch above 99 needs a wider layout; hot-fixes on the same version need a new patch number |
| Date (YYMMDDnn) | 25 09 13 01 → 25091301 | Frequent builds, CI, anything where "when" matters more than "what" | Two builds on the same day need nn incremented; it says nothing about features |
| Sequential | 1, 2, 3, … | Small apps, solo developers, ZIP rebuilds | You must remember the last one — write it in a file next to your ZIP |
Mixing schemes is fine as long as the number keeps rising. Moving from sequential (say, 14) to semantic (10402) is a jump upward and works; moving from date-based (25091301) back to semantic (10402) is a jump downward and Play will refuse it — you would be stuck with date-based forever.
What happens if you get it wrong
- Same code as the installed APK: Android says "App not installed" or silently keeps the old version. Users think the update failed.
- Lower code than Play has seen: upload rejected with "Version code X has already been used". No harm done, just re-build with a higher one.
- Different signing key: not a versioning problem, but it produces the same "App not installed" symptom — see the signing guide.
For a ZIP-to-APK app
Every rebuild from a new ZIP is a new version. The builder asks for both fields; set the name to whatever you told users and the code to something higher than last time — the planner's sequential column is the simplest habit. Keep a VERSION.txt in your project folder with the last code, and you will never guess.