An Android keystore file is a password-protected file that holds the private key and certificate you use to sign your app. Every update must be signed with that same key, so the file is the one thing you can’t lose. Keep it outside your project folder, in at least two backups, with its passwords stored somewhere else.
What an Android keystore file contains
An Android keystore file is a container for private keys and their certificates. Google’s app signing guide describes Java keystores (.jks or .keystore) as binary files that store certificates and private keys. Java’s keytool documentation agrees.
One keystore can hold more than one key. Each key inside it has a name, called an alias. When you create a key in Android Studio, the form asks for:
- Keystore password: unlocks the file itself.
- Alias: the name of the key inside the file.
- Key password: unlocks that one key.
- Certificate details: your name, organisation and a validity period.
The certificate holds the public half of the key pair, and anyone can see it. The private key proves an update came from you.
Keystore file vs the Android Keystore system
The Android Keystore system is a different thing that happens to share the name. Google’s Android Keystore system page describes an on-device API that stores cryptographic keys in a container so they’re harder to extract from the phone.
Your app’s code calls that API at runtime. The signing file sits on your computer and only matters at build time. If a search result talks about KeyGenParameterSpec or hardware-backed keys, it’s about the runtime API, not the file you’re trying to back up.
.jks, .keystore and PKCS12: does the extension matter?
The file extension doesn’t change what the keystore does. Android Studio’s wizard tells you to end the file name with .jks. The debug key it makes for you is called debug.keystore.
The format inside can differ. Older Java tools wrote the JKS format, and newer ones write PKCS #12. Per the keytool docs, most third-party tools need the store password and key password to be the same in a PKCS #12 keystore. If a build tool rejects a password you know is right, that mismatch is a common cause.
Where the keystore file lives by default
A release keystore lives wherever you saved it when you created it. Nothing moves it later, so it tends to end up in a Downloads folder or on an old laptop.
Two defaults:
- Debug keystore: Android Studio creates it at
$HOME/.android/debug.keystore. It’s for testing only. - keytool’s default: if you don’t name a destination, keytool uses
$HOME/.keystore.
Say you build a release on your work laptop with Android Studio, save upload.jks to the desktop, and move to a new machine a year later. The new machine has a fresh debug keystore but no release key. Your next update won’t sign with the right key unless you copied that file.
Where to keep each piece of your signing setup
The safest setup keeps the keystore file and its passwords in different places, so one leak or one lost laptop doesn’t cost you both. Google’s guide says to keep the keystore in a safe and secure place and to pick strong passwords for both the keystore and the key.
How I’d split the four pieces:
| Piece | Where to keep it | Why |
|---|---|---|
| Keystore file (.jks) | Encrypted cloud folder plus an offline USB drive | Two copies survive a dead laptop or a locked account |
| Keystore password | Password manager | Not next to the file it unlocks |
| Key alias | Password manager entry, same as above | Easy to forget, needed for every build |
| Key password | Password manager | Same reason as the store password |
My take: write the alias down even though it isn’t secret. People remember the file and the password, then spend an evening guessing whether the alias was key0, upload or the app name.
Keep the file out of your project’s Git repository, especially a public one. Google’s guide warns that Android Studio writes signing information in plain text into build.gradle. It tells you to move it into a separate keystore.properties file and keep that file secure, which may mean removing it from source control.
What happens if you lose the keystore file
If you lose the keystore file, whether you can still update the app depends on Play App Signing. Google’s guide says Play App Signing uses two keys: the app signing key, which Google holds, and the upload key, which you hold.
- Enrolled in Play App Signing: your file holds the upload key. Google’s docs say a separate upload key lets you request an upload key reset if it’s lost or compromised. The upload key vs app signing key post explains the split.
- Not enrolled: your file holds the app signing key. Google says that if you lose it, you lose the ability to update your app, and Google cannot retrieve it for you.
You also can’t rebuild the same key. The guide says you cannot regenerate a previously generated key, even with the same alias and password. For the full recovery options, see what happens if you lose your app signing key.
How long the key inside should last
The key in your keystore should outlive the app. Google recommends a validity period of 25 years or more, so you can sign every update with the same key. For Google Play, the key must be valid until after 22 October 2033.
If you created a key with a short validity, check it before your next big release. You can read the dates with keytool -list -v, as covered in how to sign an APK from the command line.
How a browser-based builder handles the key
A browser-based builder can store the key differently from a .jks file. In Web2Apk, signing runs in your browser and the private key is not uploaded to a build server. The key is saved as a password-encrypted backup in the browser’s storage for the site, and it isn’t synced to other devices or browsers.
That changes where you keep things. You download the encrypted key backup and keep it like a keystore file. The password needs at least 10 characters, and a forgotten password can’t be recovered. A project export includes the encrypted key but never its password.
The limitation: Web2Apk can’t import an existing JKS or P12 keystore. If your app was already signed with a keystore from Android Studio or another tool, updates must keep using that tool, because a different key won’t update the installed app. The APK signing and updates guide covers the backup steps.
Common mistakes with keystore files
Most keystore problems come from a few habits that look harmless at the time.
- Releasing with the debug keystore. It’s created for testing and differs per machine.
- One copy only. A single file on one laptop is one disk failure away from gone.
- Password in the same folder. A
passwords.txtnext torelease.jksdefeats the password. - Committing it to a public repo. Anyone who clones it gets your key file.
- Forgetting which app it signs. Name the file after the package, such as
com.example.shop-upload.jks.
If you’re unsure whether a build was signed at all, the signed vs unsigned APK post shows how to check.
FAQ
Is a .jks file the same as a .keystore file?
They’re both Java keystore files that hold certificates and private keys. The extension is just a name: Android Studio suggests .jks, while the debug key and keytool’s default use .keystore.
Should I commit my keystore file to Git?
Not to a shared or public repository. Google’s signing guide tells you to move signing passwords out of build files and to keep keystore.properties out of source control.
Can I make a new keystore if I lose the old one?
You can make a new one, but it won’t hold the same key. Google’s docs say you cannot regenerate a previously generated key, so updates signed with the new key won’t install over the old app.
Is the debug keystore enough for a release?
No. Android Studio creates the debug keystore automatically for testing. A release needs your own keystore with a key you control and back up.