Как подобрать совместимые версии Android Studio, Gradle и AGP быстро и без ошибок

Краткий ответ: определите версию Android Studio, установите рекомендованную для неё версию Android Gradle Plugin (AGP) и выставьте в gradle-wrapper минимальную (или чуть выше рекомендованной) версию Gradle; plugin id оставляйте стандартным (com.android.application / com.android.library). Ниже — таблица совместимости, конкретные команды и готовые решения типичных ошибок.

Таблица совместимости (актуально на март 2026)

Как читать: если у вас Meerkat — ставьте AGP 9.0.0 и Gradle ≥ 8.12 (рекомендуется 8.12.2). Старые Android Studio (ниже 2024.3) могут не поддерживать актуальные AGP — обновитесь.

Как подобрать и применить версии — пошагово

1. Узнайте Android Studio: Help > About. Если ниже 2024.3 — обновитесь.
2. Выберите AGP по таблице (рекомендуемая для вашей Studio).
3. Обновите Gradle wrapper до минимальной или рекомендованной версии AGP:

   ./gradlew wrapper --gradle-version 8.12.2

или вручную в gradle/wrapper/gradle-wrapper.properties:

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.12.2-all.zip

4. В корневом build.gradle (Groovy) используйте блок plugins (AGP 7.0+):

   plugins {
       id 'com.android.application' version '9.0.0' apply false
       id 'com.android.library' version '9.0.0' apply false
   }

Для Kotlin DSL (build.gradle.kts):

   plugins {
       id("com.android.application") version "9.0.0" apply false
       id("com.android.library") version "9.0.0" apply false
   }

5. В модульных build.gradle используйте только id без версии:

   plugins {
       id 'com.android.application'
       id 'org.jetbrains.kotlin.android'
   }

6. Синхронизируйте проект: Sync Project with Gradle Files. Тестируйте на эмуляторе.

Настройка plugin id и важные файлы

• Plugin id фиксирован: com.android.application (для приложений), com.android.library (для библиотек). Не придумывайте свои id.
• Откажитесь от устаревшего apply plugin: 'com.android.application' в пользу plugins {} (AGP 7.0+).
• gradle.properties — обязательные оптимизации:

  org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m
  android.useAndroidX=true
  android.enableJetifier=true
  kotlin.code.style=official

• Для M1/M2 Mac укажите путь JDK:

  org.gradle.java.home=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

Решение типичных ошибок

• "Gradle version is too old": обновите wrapper до версии, указанной в таблице (или выше на 0.1–0.2).
• "AGP requires Gradle X+": обновите Gradle wrapper; если это невозможно, понизьте AGP до совместимой версии.
• "Plugin id not found": проверьте, что в settings/build.gradle есть репозитории:

  pluginManagement {
      repositories {
          google()
          mavenCentral()
          gradlePluginPortal()
      }
  }

• Sync failed на macOS ARM: укажите org.gradle.java.home на JDK корректной архитектуры.
• Конфликты в мульти-модульных проектах: синхронизируйте AGP/Gradle по всему репозиторию, обновляйте поэтапно (Gradle → AGP → модули).

Частые ошибки

• Попытка использовать AGP с несовместимой версией Gradle. Решение: сначала обновите Gradle wrapper.
• Оставшийся apply plugin вместо plugins {} — может ломать конфигурацию при новых AGP. Мигрируйте на plugins {}.
• Несогласованные версии Kotlin Gradle Plugin и Kotlin в зависимостях — держите их в одном диапазоне.

FAQ

• Нужно ли менять plugin id для мульти-модулей?
  Нет. Для приложений — com.android.application, для библиотек — com.android.library.
• В каком порядке обновлять?
  Сначала Gradle wrapper, затем AGP, затем плагины/зависимости. Тестируйте после каждого шага.
• Можно ли сразу ставить самую свежую Gradle (например 9.0) для AGP 8.x?
  Часто да, но цель — использовать версию, совместимую с рекомендацией AGP. Проверяйте release notes.

Если после обновления остаются ошибки — дайте точный текст ошибки и содержимое gradle-wrapper.properties + корневого build.gradle, и я подскажу точечно.