Android gradle: buildtoolsVersion vs compileSdkVersion

Question

compileSdkVersion is the API version of Android that you compile against.

buildToolsVersion is the version of the compilers (aapt, dx, renderscript compiler, etc...) that you want to use. For each API level (starting with 18), there is a matching .0.0 version.

At IO 2014, we release API 20 and build-tools 20.0.0 to go with it.

Between Android releases we will release updates of the compilers, and so we'll release version .0.1, .0.2, etc... Because we don't want to silently update these version under you, it's up to you to move to the new version when it's convenient for you.

You can use a higher version of the build-tools than your compileSdkVersion, in order to pick up new/better compiler while not changing what you build your app against.

Android Studio 3.0 update

It is no longer as important to know the exact buildToolsVersion as it used to be because it is now chosen automatically.

The documentation says:

You no longer need to specify a version for the build tools (so, you can now remove the android.buildToolsVersion property). By default, the plugin automatically uses the minimum required build tools version for the version of Android plugin you're using.

Finding the exact version number

I originally came here looking for how to know the exact version number of the most recent Build Tools Version (back in the days when this needed to be updated manually). If you still need to do this, you can find it in the following way:

Go to Tools > SDK Manager > SDK Tools (tab). Select Android SDK Build Tools from the list and check Show Package Details. The last item will show the most recent version.

In the image above, I can see that I have buildToolsVersion 27.0.3 installed. There is a more recent rc (release candidate) version, but I haven't installed it. I will when the stable version comes out.