Ошибка Command failed: ./gradlew assembleDebug при сборке Kivy-приложения под Android почти всегда означает одно из двух: не установлены нужные версии SDK/NDK либо в buildozer.spec не указаны зависимости, которые ваш код импортирует. Проверка начинается не с переустановки всего toolchain, а с чтения последних 30–40 строк лога — именно там Gradle сообщает реальную причину сбоя.
Kivy — это кроссплатформенный фреймворк на Python, который позволяет написать приложение один раз и запустить его на Windows, Linux, macOS, iOS и Android. Для мобильной платформы Google код упаковывается в APK или AAB через инструменты Buildozer или p4a (python-for-android). Ниже разберём весь путь: от подготовки окружения до установки готового пакета на смартфон и диагностики типичных проблем.
Как Kivy-приложение попадает на Android
Android не исполняет Python-код напрямую: система работает с Java/Kotlin-приложениями. Поэтому при сборке в APK встраивается интерпретатор Python, библиотека SDL2 (через неё Kivy рисует интерфейс и обрабатывает касания) и сами ваши скрипты. Всё это связывается загрузчиком, который при старте запускает main.py.
Из-за такой архитектуры размер даже пустого приложения получается заметным — обычно десятки мегабайт, потому что внутри лежит целый рантайм. Это нормально и не является признаком ошибки сборки.
Подготовка окружения для сборки
Buildozer официально работает на Linux. На Windows потребуется WSL (Windows Subsystem for Linux), на macOS сборка под Android тоже возможна, но чаще встречаются конфликты зависимостей. Самый воспроизводимый вариант — Ubuntu в WSL2 или отдельная Linux-машина.
Минимальный набор действий выглядит так:
- 🐧 Установите Python 3 и пакетный менеджер pip, затем выполните
pip install buildozer. - ☕ Поставьте JDK — Buildozer подскажет нужную версию при первом запуске, если её нет.
- 📦 Установите системные зависимости:
git,zip,unzip,autoconf,libtoolи библиотеки для компиляции C-расширений. - 📱 При первой сборке Buildozer сам скачает Android SDK, NDK и необходимые инструменты — потребуется стабильный интернет и свободное место на диске (несколько гигабайт).
⚠️ Внимание: первая сборка может занять от 15 минут до часа и более — скачиваются SDK, NDK и компилируются нативные библиотеки. Не прерывайте процесс: повторный запуск продолжит с места остановки, но обрыв на этапе распаковки архивов иногда оставляет повреждённые файлы, которые потом приходится удалять вручную из каталога ~/.buildozer.
Настройка buildozer.spec
Файл buildozer.spec создаётся командой buildozer init в папке проекта и управляет всей сборкой. Ключевые параметры, которые стоит проверить в первую очередь:
- 📝
titleиpackage.name— отображаемое имя приложения и идентификатор пакета вида org.example.myapp. - 📂
source.include_exts— какие файлы попадут в APK (по умолчанию часть расширений исключена, и медиафайлы могут «потеряться»). - 🧩
requirements— здесь перечисляютpython3,kivyи все сторонние библиотеки, которые импортирует проект. - 🔐
android.permissions— разрешения вродеINTERNETилиCAMERA, без них функции приложения будут молча не работать. - 📐
orientationиfullscreen— ориентация экрана и полноэкранный режим.
Отдельного внимания заслуживает список requirements. Чисто питоновские пакеты обычно подключаются без проблем, а вот библиотеки с C-расширениями (например, numpy, Pillow) требуют специальных «рецептов» сборки в python-for-android. Если рецепта нет, пакет придётся заменять аналогом или писать рецепт самостоятельно.
Пошаговая сборка APK
Когда окружение готово и spec-файл заполнен, сборка сводится к одной команде, выполняемой из каталога проекта:
buildozer -v android debugФлаг -v включает подробный вывод — без него диагностировать сбой почти невозможно. Готовый файл появится в подкаталоге bin/ с именем вида myapp-0.1-arm64-v8a-debug.apk.
☑️ Проверка перед первой сборкой
Для установки на подключённое по USB устройство с включённой отладкой используется команда:
buildozer android debug deploy runЕсли ADB не видит смартфон, проверьте, что в настройках разработчика на устройстве включена отладка по USB, а на запрос о доверии компьютеру дан ответ «разрешить». Кабель тоже бывает причиной — некоторые шнуры передают только питание.
Типичные ошибки и их диагностика
Большинство проблем при работе Kivy на Android укладывается в несколько повторяющихся сценариев. Сводная таблица поможет быстро сориентироваться:
| Симптом | Вероятная причина | Что проверить |
|---|---|---|
| Сборка падает на этапе Gradle | Конфликт версий SDK/NDK или нехватка памяти | Хвост лога сборки, свободную RAM и диск |
| Приложение закрывается сразу после запуска | Ошибка в Python-коде или отсутствует модуль | Вывод adb logcat с фильтром по python |
| Не работает сеть/камера/файлы | Не объявлены разрешения | Секцию android.permissions в spec |
| Не находятся картинки или шрифты | Расширения не включены в APK | Параметр source.include_exts |
| ImportError для сторонней библиотеки | Нет рецепта сборки под Android | Список поддерживаемых рецептов p4a |
Главный инструмент диагностики падений на устройстве — logcat. Подключите смартфон и выполните adb logcat | grep python (или откройте полный лог и найдите traceback). Kivy выводит стандартный питоновский стек ошибки, который читается так же, как на ПК.
⚠️ Внимание: приложение, собранное в режиме debug, нельзя публиковать в Google Play — для магазина требуется release-сборка, подписанная вашим ключом, и формат AAB вместо APK. Потерянный ключ подписи невозможно восстановить: обновления приложения придётся публиковать как новое. Храните keystore и пароли от него в нескольких надёжных копиях.
Ограничения Kivy на мобильной платформе
Фреймворк рисует интерфейс собственными средствами через OpenGL, поэтому виджеты не выглядят как нативные элементы Android. Для более привычного Material-стиля существует библиотека KivyMD, но и она остаётся отрисовкой поверх SDL, а не системными компонентами.
Производительности хватает для бизнес-утилит, списков, форм и несложной графики. Для тяжёлых 3D-игр или интенсивной обработки видео Python-стек уступает нативной разработке. Также учитывайте ограничения фоновой работы: Android агрессивно выгружает процессы, и для фоновых задач нужен отдельный сервис — python-for-android умеет их создавать, но настройка заметно сложнее обычного приложения.
Альтернатива Buildozer — p4a напрямую
Инструмент python-for-android можно вызывать без Buildozer, передавая параметры через командную строку: p4a apk --requirements=python3,kivy --private ./myapp --package=org.example.myapp --name MyApp. Это даёт более тонкий контроль, но требует ручного управления версиями SDK/NDK. Для первых проектов Buildozer удобнее, так как автоматизирует рутину.
Обновление и публикация приложения
Когда отладочная версия стабильно работает, переходите к релизу. Сборка выполняется командой buildozer android release, после чего APK нужно подписать своим ключом и выровнять. Ключ создаётся один раз утилитой keytool из состава JDK — параметры вроде имени и срока действия вы задаёте сами.
При каждом обновлении увеличивайте version.code в buildozer.spec — именно по этому числу Android и Google Play определяют, что пакет новее установленного. Если код версии не изменить, обновление просто не установится поверх предыдущей сборки.
Часто задаваемые вопросы
Можно ли собрать Kivy-приложение под Android на Windows без Linux?
Напрямую — нет, Buildozer требует Linux-окружение. Рабочие варианты: WSL2 на Windows 10/11, виртуальная машина с Ubuntu или облачная сборка через CI-сервисы. Через WSL2 сборка проходит штатно, но первый запуск требует времени на скачивание SDK и NDK.
Почему приложение вылетает сразу после заставки?
Чаще всего это необработанное исключение в Python-коде или отсутствующий модуль. Подключите устройство по USB и посмотрите traceback через adb logcat — там будет точная строка ошибки, как при обычном запуске скрипта.
Какой размер APK считается нормальным для Kivy?
Даже минимальное приложение весит десятки мегабайт, потому что внутри находятся интерпретатор Python и SDL2. Это ожидаемое поведение, а не признак проблемы. Уменьшить размер можно, исключив лишние файлы и собрав пакет только под нужные архитектуры процессора.
Работают ли все Python-библиотеки на Android?
Нет. Чисто питоновские пакеты обычно работают, а библиотеки с C-расширениями требуют рецепта сборки в python-for-android. Для популярных пакетов (numpy, Pillow и других) рецепты существуют, для редких — придётся искать замену.
Можно ли опубликовать debug-версию APK в Google Play?
Нет. Консоль Google Play принимает только подписанные релизные сборки в формате AAB. Потребуется создать собственный ключ подписи и собрать release-версию через Buildozer.