What is the difference between compileSdkVersion and targetSdkVersion?

Question

I have looked at the documentation for building with Gradle, but I'm still not sure what the difference between compileSdkVersion and targetSdkVersion is.

All it says is:

The compileSdkVersion property specifies the compilation target.

Well, what is the "compilation target"?

I see two possible ways to interpret this:

1. compileSdkVersion is the version of the compiler used in building the app, while targetSdkVersion is the "API level that the application targets". (If this were the case, I'd assume compileSdkVersion must be greater than or equal to the targetSdkVersion?
2. They mean the same thing. "compilation target" == "the API level that the application targets"
3. Something else?

I see that this question has been asked before, but the one answer just quotes the doc, which is what is unclear to me.

Solution 1

compileSdkVersion

The compileSdkVersion is the version of the API the app is compiled against. This means you can use Android API features included in that version of the API (as well as all previous versions, obviously). If you try and use API 16 features but set compileSdkVersion to 15, you will get a compilation error. If you set compileSdkVersion to 16 you can still run the app on a API 15 device as long as your app's execution paths do not attempt to invoke any APIs specific to API 16.

targetSdkVersion

The targetSdkVersion has nothing to do with how your app is compiled or what APIs you can utilize. The targetSdkVersion is supposed to indicate that you have tested your app on (presumably up to and including) the version you specify. This is more like a certification or sign off you are giving the Android OS as a hint to how it should handle your app in terms of OS features.

For example, as the documentation states:

For example, setting this value to "11" or higher allows the system to apply a new default theme (Holo) to your app when running on Android 3.0 or higher...

The Android OS, at runtime, may change how your app is stylized or otherwise executed in the context of the OS based on this value. There are a few other known examples that are influenced by this value and that list is likely to only increase over time.

For all practical purposes, most apps are going to want to set targetSdkVersion to the latest released version of the API. This will ensure your app looks as good as possible on the most recent Android devices. If you do not specify the targetSdkVersion, it defaults to the minSdkVersion.

Solution 2

As a oneliner guide:

minSdkVersion <= targetSdkVersion <= compileSdkVersion

---

Ideally:

minSdkVersion (lowest possible) <= targetSdkVersion == compileSdkVersion (latest SDK)

---

Read more from this great post by Ian Lake

Solution 3

Late to the game.. and there are several great answers above-- essentially, that the compileSdkVersion is the version of the API the app is compiled against, while the targetSdkVersion indicates the version that the app was tested against.

I'd like to supplement those answers with the following notes:

1. That targetSdkVersion impacts the way in which permissions are requested:

• If the device is running Android 6.0 (API level 23) or higher, and the app's targetSdkVersion is 23 or higher, the app requests permissions from the user at run-time.
• If the device is running Android 5.1 (API level 22) or lower, or the app's targetSdkVersion is 22 or lower, the system asks the user to grant the permissions when the user installs the app.

2. If the compileSdkVersion is higher than the version declared by your app's targetSdkVersion, the system may enable compatibility behaviors to ensure that your app continues to work the way you expect. (ref)

3. With each new Android release...

• targetSdkVersion should be incremented to match the latest API level, then thoroughly test your application on the corresponding platform version
• compileSdkVersion, on the other hand, does not need to be changed unless you're adding features exclusive to the new platform version
• As a result, while targetSdkVersion is often (initially) less than than the compileSdkVersion, it's not uncommon to see a well-maintained/established app with targetSdkVersion > compileSdkVersion

Solution 4

The compileSdkVersion should be newest stable version. The targetSdkVersion should be fully tested and less or equal to compileSdkVersion.

Solution 5

The CompileSdkVersion is the version of the SDK platform your app works with for compilation, etc DURING the development process (you should always use the latest) This is shipped with the API version you are using

You will see this in your build.gradle file:

targetSdkVersion: contains the info your app ships with AFTER the development process to the app store that allows it to TARGET the SPECIFIED version of the Android platform. Depending on the functionality of your app, it can target API versions lower than the current.For instance, you can target API 18 even if the current version is 23.

Take a good look at this official Google page.

View more solutions

Comments

[coder123]

I see. So the targetSdkVersion should never be greater than the compileSdkVersion -- is that correct?

[Jeffrey Mixon]

No, targetSdkVersion very likely will be higher than compileSdkVersion and rightfully so. This means that although you designed an app to target API 16, for example, it still runs fine on API 21 (Lollipop) and you should bump your targetSdkVersion to 21 to indicate it is okay for the Android OS to apply any Lollipop-styles that may exist to your app.

[coder123]

You said earlier: "If you try and use API 16 features but set compileSdkVersion to 15, you will get a compilation error." In your second comment, it sounds like you're saying compileSdkVersion can be 15, and targetSdkVersion can be (and very likely is) higher than 15, say 16. Does that not mean I've "certified" the app to work with API 16 and its features?

[coder123]

Fundamentally, I don't understand how you could target an SDK higher than the the SDK you've compiled against.

[Jeffrey Mixon]

Changing compileSdkVersion to a higher version would mean you want to use some new APIs that are only included in that particular release. If you don't plan on using any Lollipop-specific features in your app, then there's really (usually) no reason to ever set compileSdkVersion to 21. However, your app will likely run just fine on API 21 as-is, thus you change targetSdkVersion to indicate your app runs like you expect (target) on API 21, but you're not using any APIs specific to 21 (compile) and thus your compileSdkVersion can stay at 15 in this example.

[Pelpotronic]

A warning is reported when I do that in Android studio. I have "compileSdkVersion 17" and "targetSdkVersion 22" and it tells me "targetSdkVersion should not be higher than compileSdkVersion". Oh, just changed it and now it's telling me the targetSdkVersion is not the latest 22 and that compatibility mode might kick in. Sigh.

[Sufian]

Any specific reason for saying that targetSdkVersion be less than compileSdkVersion? I believe it's a wrong statement

[espinchi]

Many developers are gonna want to set compileSdkVersion 23 but stay with targetSdkVersion 22 for a while. (See @jeff-mixon comment for the reason.)

[Dielson Sales]

I guess the point is that the last version is backwards compatible, so the latest API version can "behave" like older ones, if you set the targetSdkVersion to a lower one. So the targetSdkVersion should be the one you have tested and know the exact behavior, and can be <= the latest stable.

[degill]

I still dont 100% get what compileSdkVersion means. Lets say I have an app which I build on API Level 21. Then Google releases API 23. I compile my App against compileSdkVersion 23 BUT did not change anything besides that in my code. Will my app use the 'new' code from API 23? I am asking because Im curious what happens with bug fixes: Lets say there was a method DoStuff() which I use in my APP. Google noticed that it contains a bug and they fixed it for API 23. When I compile with compileSdkVersion 23 does my App get that bugfix? Will that code from that SDK be compiled into my app?

[Jeffrey Mixon]

@degill compileSdkVersion only affects compilation time. The API level of the device determines which version of Android it is ultimately running against. An app with an compileSdkVersion of 11 running on a device with API 21 will run version 21 of all the Android APIs. compileSdkVersion is purely for the compiler; it does not influence anything after your app is already built.

[Murphybro2]

It clearly states in android studio when you set the targetSdkVersion higher than compileSdkVersion.. "The targetSdkVersion should not be higher than the compileSdkVersion"

[ARK]

This answer contradicts what the Android Studio says. targetSdkVersion matters and it should less than or equal to compileSdkVersion

[Jeffrey Mixon]

That is just a Gradle inspection hint for convenience. There is no actual technical issue with setting targetSdkVersion higher than compileSdkVersion. At the same time, it doesn't really hurt to also set compileSdkVersion to the highest level either, as long as you understand the implications.

[MD-11]

"Note that if you use the Support Library, compiling with the latest SDK is a requirement for using the latest Support Library releases." source: medium.com/google-developers/…

[Caltor]

I don't think the Android advice is different. There's a difference between "compile your application against the lowest possible version" and compiling with a particular SDK version. You should generally compile (compileSdkVersion) with the latest version, set your min (minSdkVersion) as low as possible and set your target (targetSdkVersion) as high as possible subject to testing or other compatibility issues.

[Jeremy]

Re: your second point, I don't think the references doc explicitly says that. It says "However, if the API level of the platform is higher than the version declared by your app's targetSdkVersion, the system may enable compatibility behaviors to ensure that your app continues to work the way you expect." I think this means if the API level of the device you are running on is newer than your targetSdkVersion you may see compatibility behaviors. I don't believe it has anything to do with the compileSdkVersion.

[Jeremy]

Good point @Caltor. I wish they would update that document to clarify the difference. The <uses-sdk> documentation is extremely vague and ambiguous.

[Jaime Montoya]

I did not understand this part of your answer: "as long as your app's execution paths do not attempt to invoke any APIs specific to API 16". Is it safe to set compileSdkVersion to 16 run the app on an API 15 device?

[user239558]

The most important issue is - is it compileSdkVersion or targetSdkVersion that can never be downgraded in google play?

[Erik]

I think that your statement 'compileSdkVersion should be newest stable version' should be suffixed with 'of which you use API features'. It makes no sense to compile against API 27 (today's latest stable API) if you only use lower API version features. However, the latest stable version could include some features that automatically become better, e.g. enhanced security or efficient compilation with backwards compatibility. Therefore it is advisable to use the latest or at least a recent stable version, but it 'should [not] be' the latest version per se.

[joelw]

"This means you can use Android API features included in that version of the API (as well as all previous versions, obviously)." I don't think it is correct that you can use all feature included in previous versions. If a method was present (but deprecated) in 15, then removed in 16, you can't use it if the compileSdkVersion is set to 16 or greater.

[Nitin Bansal]

Does minSdkVersion means the lowest device api level app can run on? Presumably because it uses certain API's available from minSdkVersion onwards?

[Admin]

In Android Studio, if I set compileSdkVersion lower than targetSdkVersion then AS tells me this is not allowed, so it seems to me you should not set compiled < target as mentioned above... (@Jeff Mixon ?)

[Louis Tsai]

@NitinBansal yes. For example if minSdkVersion is 15 (which is ICS 4.0.3), devices with API 14 (which is ICS 4.0) should not be able to install the app. And at least for now, the app will run on 15, 16, 17, 18, 19, (20 but that's for the old wear os), 21, 22, 23, 24, 25, 26, 27, 28, and so on in the future (probably)

[Shitesh]

I struggle with the phrase "compiled against". To me it sounds like it means, "the byte code coming out of the compiler is this version". But it seems to be used as "the version of the compiler used is this version". That totally changes the meaning. I'd imagine a newer compiler can generate back-compatible byte code, but newer byte code cannot run on an older OS.

[Suraj Vaishnav]

If the compileSdkVersion is 23 and targetSdkVersion is 22, would it show permission dialog in the marshmallow and above devices?

[ahmednabil88]

"target version" is obviously not lower than your "minimum SDK version"

[minsk]

with this explanation, compileSdkVersion should always be set to min sdk or there is chance of breaking ?

[Salim Mazari Boufares]

Practically scenario A can be true only if TargetSdkVersion = CompileSdkVersion but not higher, when you chose a higher value Android Studio will consider it as an error and request from you to chose a value that is equal or lower than the ComplieSdkVersion

[Kleysley]

the targetSdkVersion should not be higher than the compileSdkVersion. compileSdkVersion should NOT be set depending on the minSdkVersion but depending on the targetSdkVersion. If your targetSdkVersion and the minSdkVersion are the same, then obviously the compileSdkVersion should also be the same. There isn't any chance of breaking, but the compileSdkVersion says what featues are possible so....

[Kleysley]

Any features in higher SDKs than the compileSDK cant be used. So setting your targetSdkVersion above your compileSdkVersion is like saying: "This is built for [targetSdkVersion], but you only get the features from [compileSdkVersion]!"

[djzhao]

compileSdkVersion can be less than targetSdkVersion

[Jimmy Kane]

@djzhao care to elaborate why?

[jaquinocode]

@JimmyKane Not sure if you already saw this, but this comment sort of explains why you would maybe want to do that (not saying I would recommend it, just relaying info).