compileSdkVersion: Basics, New APIs, and Gradle Configuration

What is compileSdkVersion in Android?

compileSdkVersion is an integer parameter in build.gradle that specifies which version of the Android SDK to compile code against. When you write code using classes from android.* or androidx.*, the compiler checks them against the APIs available in the specified compileSdk version. If a method was introduced in API 36 and compileSdk = 35, the code will not compile. If compileSdk = 36, the code will compile, but calling that method on a device with API 35 without a check will cause a crash.

compileSdkVersion is loaded from the Android SDK Platform installed via SDK Manager in Android Studio. Each API Level has its own platform: android-21, android-29, android-34, android-35, android-36. The platform contains android.jar — a set of classes, methods, and constants that the Kotlin/Java compiler uses. If the platform is not installed, Gradle will download it automatically via sdkmanager on the first build.

AGP (Android Gradle Plugin) version 8.7+ recommends specifying compileSdk as an integer via compileSdk = 36 in Kotlin DSL, without the android- prefix. compileSdk can also be set via compileSdkVersion 36 in Groovy DSL or compileSdkPreview for pre-release SDK versions (developer previews). compileSdkPreview is used for testing upcoming API Levels before the official release.

// build.gradle.kts — compileSdkVersion configuration
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — latest stable API Level (Android 16)
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }
}

// Alternatively: compileSdkPreview for preview versions
// compileSdkPreview = "Baklava"

In the example, compileSdk = 36 provides access to all Android 16 (Baklava) APIs. Android SDK Platform 36 must be installed in SDK Manager. compileSdkPreview with the name "Baklava" can be used to test unstable APIs before the official platform release. After the release, the preview is replaced with stable compileSdk = 36.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Three API Level parameters in build.gradle — compileSdkVersion, targetSdkVersion, and minSdkVersion — are often confused. Each is responsible for a different aspect of compatibility, and their values must follow the rule compileSdk >= targetSdk >= minSdk. minSdk is the lower bound: devices below it will not see the app. targetSdk is the testing point: behavioral changes are enabled up to this level. compileSdk is the ceiling: APIs above this level are unavailable to the compiler.

Key practical rule: compileSdk can be increased without any device testing. This is a safe operation that simply provides the compiler with a new version of android.jar. The only risk is deprecated APIs that may be removed in the new platform version, but this is detected at compile time and easily fixed. Increasing targetSdk, on the other hand, requires a full QA cycle.

Why can compileSdk be higher than targetSdk? Imagine Android 16 (API 36) was released with new APIs you want to use in code, but you haven't tested the behavioral changes of API 36 yet. You set compileSdk = 36 (new APIs available), targetSdk = 35 (API 36 behavioral changes disabled). The code will compile, use new methods under SDK_INT guards, and behavioral changes of API 36 won't break the app because targetSdk = 35.

Examples of correct combinations

compileSdk = 36, targetSdk = 36, minSdk = 26 — full compatibility with the latest APIs and behavioral changes, covering 85% of devices. compileSdk = 36, targetSdk = 34, minSdk = 26 — new APIs available, behavioral changes only up to API 34. compileSdk = 35, targetSdk = 36 — incorrect: compileSdk is lower than targetSdk, API 36 is unavailable while behavioral changes of 36 are active.

How to Update compileSdkVersion: Step-by-Step Guide

Updating compileSdkVersion is one of the simplest and safest operations in an Android project. Unlike targetSdk, it does not require extensive testing of behavioral changes. However, there are a few steps to follow to avoid compilation errors and deprecated warnings.

Step 1 — install the new platform via SDK Manager in Android Studio: Tools → SDK Manager → SDK Platforms → select the new API Level. If you don't install the platform, Gradle will try to download it automatically, but this may slow down the first build. Step 2 — change compileSdk in build.gradle to the new value. Step 3 — build (Build → Make Project) and fix any compilation errors.

Step 4 — check for deprecated APIs. After upgrading compileSdk, some methods may be marked @Deprecated with a note "removed in API X". Android Studio highlights them with strikethrough and shows a warning. Replace deprecated calls with new alternatives. If the alternative requires an API Level higher than minSdk, add a runtime check. Step 5 — check dependencies: some libraries may require a specific compileSdk version. AGP 8.7+ recommends compileSdk = 36.

// After upgrading compileSdk: replacing deprecated APIs
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // BEFORE: deprecated method (may be removed in the new API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // May be deprecated in API 36
    }

    // AFTER: new alternative (if available)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // New API from compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Example of new API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

The CompileSdkMigration class demonstrates the correct migration pattern. The old method memoryClass may be removed in the new API — the compiler will throw an error. The new alternative getMemoryClassSafe is only available on API 36+, so it is called under a SDK_INT >= BAKLAVA check. For older devices, a fallback with @Suppress("DEPRECATION") is used.

Working with New APIs: Conditional Checks and Fallback

New APIs made available by upgrading compileSdkVersion cannot be called directly if minSdkVersion is lower than that API Level. Without a runtime check, the app will crash with AbstractMethodError, NoSuchMethodError, or VerifyError on older devices. The primary protection mechanism is checking Build.VERSION.SDK_INT, calling the new API only when the API Level is sufficient, and providing a fallback for older versions.

AndroidX provides backports for many new APIs, allowing you to use modern methods even with a low compileSdk. For example, the Activity Result API from androidx.activity:activity-ktx:1.9.3 works on all Android versions starting from API 14. NotificationCompat from AndroidX enables modern notifications on old APIs. PhotoPicker is available via ActivityResultContracts.PickVisualMedia starting from API 34+.

// Safe call of new API with compileSdk 36 and minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: new method for working with color
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // New API from compileSdk 36 — requires API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: manual formatting for old APIs
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: no backport needed — SDK_INT check
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Usage in Activity
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

The NewApiHelper class demonstrates safe calling of the new API Color.toArgbHexString (hypothetical API 36) with fallback formatting for older versions. The key principle: compileSdk gives access to calling new methods in code, but a runtime SDK_INT check protects against crashes on older devices. Without an SDK_INT check, an app with minSdk 26 and compileSdk 36 will crash on Android 8-15.

AGP (Android Gradle Plugin) and compileSdkVersion

Android Gradle Plugin (AGP) is the primary build tool for Android applications. Each AGP version supports a specific range of compileSdkVersion. AGP 8.7.x (released in 2026) requires compileSdk >= 34 and recommends compileSdk = 36. AGP 8.5.x supports compileSdk 33-35. If compileSdk is below the minimum for AGP, the build will fail with an error: "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) is also tied to compileSdkVersion. If your project uses native C/C++ code via NDK, compileSdk determines the version of header files and libraries. NDK r27+ recommends compileSdk 36. For libraries with .so files, compileSdk affects the minimum API Level for native code via APP_MIN_SDK_VERSION in Application.mk.

Gradle (7.6+) and Kotlin (2.0+) also affect compileSdk compatibility. AGP 8.7+ requires Gradle 8.9+ and Kotlin 2.0+. When upgrading compileSdk, it is recommended to update AGP, Gradle, and Kotlin to the latest stable versions. Check compatibility in the official Android Gradle Plugin compatibility table.

Common Problems When Upgrading compileSdk

Problems when upgrading compileSdkVersion fall into three categories: compilation errors, deprecated warnings, and runtime incompatibilities. Compilation errors — methods are removed from the API and the code does not compile. Deprecated warnings — methods are marked @Deprecated, the code compiles with warnings. Runtime incompatibilities — new APIs are required for certain functionality and cause errors if the API Level on the device is insufficient.

The first common problem — "Cannot resolve symbol X". This means a class or method was removed from the public API in the new SDK version. Solution: find an alternative in the new platform or use an AndroidX equivalent. For example, the AsyncTaskLoader class was deprecated in API 28 and removed from the public API in newer versions. Alternatives include Kotlin Coroutines or WorkManager.

The second problem — method signature change. In the new API version, a method may have changed the number or types of its parameters. The Kotlin/Java compiler throws an error: "None of the following functions can be called with the arguments supplied". Solution: update the method call to match the new signature or add an SDK_INT check with the old signature call for older devices.

// Solving problems when upgrading compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problem: method hasSystemFeature changed signature in API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // New signature: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Old signature: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problem: class removed, use AndroidX equivalent
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Instead of android.app.FragmentManager (removed) use
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

The CompileSdkProblemFixer class solves common problems: the changed signature of hasSystemFeature (hypothetical change in API 36) is handled via an SDK_INT check calling the correct method version. The removed class android.app.FragmentManager is replaced with its AndroidX equivalent. For old calls where no alternative exists, @Suppress("DEPRECATION") is used with a comment explaining the reason for keeping it.