Android 스튜디오 빌드 시스템은 Gradle을 기반으로 하며 Android Gradle 플러그인에는 Android 앱을 빌드하는 데 사용하는 몇 가지 추가 기능이 있습니다.
이 페이지에서는 Gradle 도구를 최신 상태로 유지하는 방법을 설명합니다. Android Gradle 플러그인에 관한 출시 노트는 출시 노트 페이지를 참고하세요.
Android Gradle 플러그인의 예정된 브레이킹 체인지를 개략적으로 알아보려면 Android Gradle 플러그인 로드맵을 참고하세요.
Gradle을 사용하여 Android 빌드를 구성하는 방법에 관한 자세한 내용은 다음 페이지를 참고하세요.
Gradle 빌드 시스템에 관한 자세한 내용은 Gradle 사용자 가이드를 참고하세요.
Android Gradle 플러그인 업데이트
Android 스튜디오를 업데이트하면 Android Gradle 플러그인을 사용 가능한 최신 버전으로 자동 업데이트하라는 메시지가 표시될 수 있습니다. 업데이트를 수락하거나 프로젝트의 빌드 요구사항에 따라 버전을 수동으로 지정할 수 있습니다.
Android 스튜디오의 File > Project Structure > Project 메뉴 또는 최상위 build.gradle.kts 파일에서 플러그인 버전을 지정할 수 있습니다. 플러그인 버전은 Android 스튜디오 프로젝트에 빌드된 모든 모듈에 적용됩니다. 다음 예는 build.gradle.kts 파일에서 플러그인을 버전 9.0으로 설정합니다.
Kotlin
plugins { id("com.android.application") version "9.0" apply false id("com.android.library") version "9.0" apply false id("org.jetbrains.kotlin.android") version "2.2.21" apply false }
Groovy
plugins { id 'com.android.application' version '9.0' apply false id 'com.android.library' version '9.0' apply false id 'org.jetbrains.kotlin.android' version '2.2.21' apply false }
주의: 버전 번호에 동적 종속 항목을 사용해서는 안 됩니다(예: 'com.android.tools.build:gradle:9.+').
이 기능을 사용하면 예상하지 못한 버전 업데이트가 발생할 수 있고 버전 차이를 해결하기 어려울 수 있습니다.
지정된 플러그인 버전을 다운로드하지 않은 경우, 다음에 프로젝트를 빌드할 때 또는 Android 스튜디오 메뉴 바에서 File > Sync Project with Gradle Files를 클릭하면 Gradle에서 지정된 버전의 플러그인을 다운로드합니다.
Gradle 업데이트
Android 스튜디오를 업데이트하면 Gradle 또한 사용 가능한 최신 버전으로 업데이트하라는 메시지가 표시될 수 있습니다. 업데이트를 수락하거나 프로젝트의 빌드 요구사항에 따라 버전을 수동으로 지정할 수 있습니다.
다음 표는 각 버전의 Android Gradle 플러그인에 필요한 Gradle 버전을 보여줍니다. 최상의 성능을 위해서는 Gradle과 플러그인을 가능한 최신 버전으로 사용해야 합니다.
| 플러그인 버전 | 필요한 최소 Gradle 버전 |
|---|---|
| 9.0 | 9.1.0 |
| 8.13 | 8.13 |
| 8.12 | 8.13 |
| 8.11 | 8.13 |
| 8.10 | 8.11.1 |
| 8.9 | 8.11.1 |
| 8.8 | 8.10.2 |
| 8.7 | 8.9 |
| 8.6 | 8.7 |
| 8.5 | 8.7 |
| 8.4 | 8.6 |
| 8.3 | 8.4 |
| 8.2 | 8.2 |
| 8.1 | 8.0 |
| 8.0 | 8.0 |
이전 버전
| 플러그인 버전 | 필요한 Gradle 버전 |
|---|---|
| 7.4 | 7.5 |
| 7.3 | 7.4 |
| 7.2 | 7.3.3 |
| 7.1 | 7.2 |
| 7.0 | 7.0 |
| 4.2.0+ | 6.7.1 |
| 4.1.0+ | 6.5+ |
| 4.0.0+ | 6.1.1+ |
| 3.6.0~3.6.4 | 5.6.4+ |
| 3.5.0~3.5.4 | 5.4.1+ |
| 3.4.0~3.4.3 | 5.1.1+ |
| 3.3.0~3.3.3 | 4.10.1+ |
| 3.2.0~3.2.1 | 4.6+ |
| 3.1.0+ | 4.4+ |
| 3.0.0+ | 4.1+ |
| 2.3.0+ | 3.3+ |
| 2.1.3~2.2.3 | 2.14.1~3.5 |
| 2.0.0~2.1.2 | 2.10~2.13 |
| 1.5.0 | 2.2.1~2.13 |
| 1.2.0~1.3.1 | 2.2.1~2.9 |
| 1.0.0~1.1.3 | 2.2.1~2.3 |
Android 스튜디오의 File > Project Structure > Project 메뉴에서 Gradle 버전을 지정하거나 명령줄을 사용하여 Gradle 버전을 업데이트할 수 있습니다.
선호되는 방법은 Gradle Wrapper 명령줄 도구를 사용하여 gradlew 스크립트를 업데이트하는 것입니다. 다음 예는 Gradle Wrapper를 사용하여 Gradle 버전을 9.1.0으로 설정합니다.
Gradle과 Gradle Wrapper 자체를 모두 업그레이드하려면 이 명령어를 두 번 실행해야 합니다(자세한 내용은 Gradle Wrapper 업그레이드 참고).
gradle wrapper --gradle-version 9.1.0
그러나 AGP를 업데이트했는데 더 이상 현재 Gradle 버전과 호환되지 않는 등의 일부 경우에는 실패할 수 있습니다. 이 경우 gradle/wrapper/gradle-wrapper.properties 파일에서 Gradle 배포 참조를 수정해야 합니다. 다음 예는 gradle-wrapper.properties 파일에서 Gradle 버전을 9.1.0으로 설정합니다.
...
distributionUrl = https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip
...
Android Gradle 플러그인과 Android 스튜디오 호환성
Android 스튜디오 빌드 시스템은 Gradle을 기반으로 하며 Android Gradle 플러그인(AGP)에는 Android 앱을 빌드하는 데 사용하는 몇 가지 추가 기능이 있습니다. 다음 표에는 각 버전의 Android 스튜디오에 필요한 AGP 버전이 나열되어 있습니다.
| Android 스튜디오 버전 | 필요한 AGP 버전 |
|---|---|
| Otter 3 기능 출시 | 2025년 2월 3일 | 4.0~9.0 |
| Otter 2 기능 출시 | 2025년 2월 2일 | 4.0~8.13 |
| Otter | 2025.2.1 | 4.0~8.13 |
| Narwhal 4 기능 출시 | 2025.1.4 | 4.0~8.13 |
| Narwhal 3 기능 출시 | 2025.1.3 | 4.0~8.13 |
| Narwhal 기능 출시 | 2025.1.2 | 4.0~8.12 |
| Narwhal | 2025.1.1 | 3.2~8.11 |
| 미어캣 기능 출시 | 2024.3.2 | 3.2~8.10 |
| Meerkat | 2024.3.1 | 3.2~8.9 |
이전 버전
| Android 스튜디오 버전 | 필요한 AGP 버전 |
|---|---|
| 무당벌레 기능 출시 | 2024.2.2 | 3.2~8.8 |
| Ladybug | 2024.2.1 | 3.2~8.7 |
| Koala 기능 출시 | 2024.1.2 | 3.2~8.6 |
| Koala | 2024.1.1 | 3.2~8.5 |
| Jellyfish | 2023.3.1 | 3.2~8.4 |
| Iguana | 2023.2.1 | 3.2~8.3 |
| Hedgehog | 2023.1.1 | 3.2-8.2 |
| Giraffe | 2022.3.1 | 3.2~8.1 |
| Flamingo | 2022.2.1 | 3.2~8.0 |
| Electric Eel | 2022.1.1 | 3.2~7.4 |
| Dolphin | 2021.3.1 | 3.2~7.3 |
| Chipmunk | 2021.2.1 | 3.2~7.2 |
| Bumblebee | 2021.1.1 | 3.2~7.1 |
| Arctic Fox | 2020.3.1 | 3.1~7.0 |
Android Gradle 플러그인의 새로운 기능에 관한 정보는 Android Gradle 플러그인 출시 노트를 참고하세요.
Android API 수준 도구 최소 버전
특정 API 수준을 지원하는 최소 버전의 Android 스튜디오와 AGP가 있습니다. 프로젝트의 targetSdk 또는 compileSdk에 필요한 버전보다 낮은 버전의 Android 스튜디오 또는 AGP를 사용하면 예기치 않은 문제가 발생할 수 있습니다. Android OS의 미리보기 버전을 타겟팅하는 프로젝트에서 작업하려면 Android 스튜디오와 AGP의 최신 미리보기 버전을 사용하는 것이 좋습니다. 안정화 버전과 함께 Android 스튜디오의 미리보기 버전을 설치할 수 있습니다.
Android 스튜디오 및 AGP의 최소 버전은 다음과 같습니다.
| API 수준 | Android 스튜디오 최소 버전 | AGP 최소 버전 |
|---|---|---|
| 36.1 | Narwhal 3 기능 출시 | 2025.1.3 | 8.13.0 |
| 36.0 | Meerkat | 2024.3.1 패치 1 | 8.9.1 |
| 35 | Koala 기능 출시 | 2024.2.1 | 8.6.0 |
| 34 | Hedgehog | 2023.1.1 | 8.1.1 |
| 33 | Flamingo | 2022.2.1 | 7.2 |