The CommonsBlog

Android Studio and distributionSha256Sum

It is common, though perhaps not widespread, to be given a checksum or hash when you go to download something. For example, when you go to download a Google Pixel image for Android P, you are given SHA-256 checksums for the ZIP files. That way, you can confirm that the ZIP file was downloaded correctly. Back in the early days of the Internet, checksums were good for confirming that some bits didn’t get flipped by accident in your download.

(if you’re under 40, ask your parents about “dial-up Internet”)

Nowadays, though, the concern is security. Having a separate checksum makes it a bit more difficult for an attacker to substitute a hacked file for the real one that you are trying to download.

Gradle offers support for this as part of the Gradle Wrapper. In addition to having a distributionUrl line in, you can have a distributionSha256Sum line with a SHA-256 checksum for the Gradle ZIP listed in the distributionUrl. So, for example, if you have:


you can also have:


You have to get the SHA-256 checksum value yourself, from the server that has the ZIP files. When the Gradle tooling API, gradlew, or gradlew.bat need to download Gradle, they will check the SHA-256 hash of the downloaded ZIP file against the supplied distributionSha256Sum. If there is a mismatch, that ZIP will not be unpacked.

Ideally, we would have distributionSha256Sum values in all of our files. Instead, few do, for (at least) two reasons.

First, the process is very manual. Android Studio could add the appropriate value when it creates or modifies the file. It doesn’t, though, so developers need to go get these values themselves, or hope that somebody gives them a tool that simplifies it a bit.

Second, if there is a mismatch between the SHA-256 checksum and the actual ZIP file hash… Android Studio crashes hard, without even an error dialog. Android Studio needs a better UX here. That in turn might require fixes to the Gradle tooling API to provide more options for handling this situation, though it has been a couple of years since I filed the issue to try to stop Android Studio from crashing here.

Long-term, with some amount of luck, these things will get addressed. I look forward to someday having distributionSha256Sum in more Android projects.

Do you need a book on Android app development, but are having trouble finding one that is new enough? Try The Busy Coder’s Guide to Android Development!