Команда buildozer android debug зависла на этапе скачивания SDK или завершилась ошибкой «No module named 'kivy'» — типичная точка, с которой начинается знакомство с конвертацией Python в APK. Проблема почти всегда кроется не в самом коде, а в окружении сборки: отсутствующие зависимости, неверная версия Android NDK или запуск Buildozer под Windows, где он официально не работает.
APK-файл из Python-скрипта собрать реально, но важно понимать: Android не исполняет Python нативно. Готовый пакет содержит встроенный интерпретатор, ваши модули и обёртку-загрузчик, поэтому итоговый файл получается заметно тяжелее аналогичного приложения на Java или Kotlin. Ниже разберём рабочие инструменты, порядок сборки и типовые ошибки, которые встречаются чаще всего.
Как устроена конвертация Python в APK
APK — это архив с DEX-байткодом, ресурсами и манифестом, который исполняет виртуальная машина Android Runtime. Python-код в такой пакет попадает в исходном виде вместе с переносимой сборкой интерпретатора CPython, скомпилированной под архитектуры ARM. При запуске приложения сначала стартует нативный загрузчик, который поднимает интерпретатор и передаёт ему управление.
Из этого следуют два практических ограничения. Во-первых, размер APK редко опускается ниже 15–20 МБ даже для пустого проекта, потому что интерпретатор и стандартная библиотека идут в комплекте. Во-вторых, библиотеки с нативными расширениями (numpy, pandas, cryptography) требуют отдельных рецептов кросс-компиляции — если рецепта нет, пакет в сборку не попадёт.
Обзор инструментов: Buildozer, Kivy, PyDroid3 и альтернативы
Выбор инструмента зависит от того, где вы собираете проект и какой интерфейс нужен приложению. Универсального решения «нажал кнопку — получил APK» не существует; у каждого подхода есть свои ограничения по окружению и поддерживаемым библиотекам.
- 🛠️ Buildozer — основной инструмент для связки Python + Kivy, автоматизирует скачивание SDK/NDK и сборку через python-for-android.
- 📱 PyDroid3 — IDE прямо на Android-смартфоне, позволяет экспортировать проект в APK без компьютера, но с ограниченным набором библиотек.
- 🐝 BeeWare (Briefcase) — набор инструментов для нативных интерфейсов; поддержка Android существует, но экосистема заметно моложе, чем у Kivy.
- ☕ Chaquopy — плагин для Android Studio, встраивающий Python в стандартный Gradle-проект; подходит тем, кто готов писать обвязку на Kotlin/Java.
Если нужен быстрый результат без установки Linux, начните с PyDroid3. Если планируете публиковать приложение и вам важны контроль над сборкой и поддержка сторонних пакетов — осваивайте Buildozer.
| Инструмент | Платформа сборки | Сложность | Кому подходит |
|---|---|---|---|
| Buildozer | Linux / WSL / macOS | Средняя | Проекты на Kivy |
| PyDroid3 | Сам Android | Низкая | Прототипы, обучение |
| BeeWare Briefcase | Windows, Linux, macOS | Средняя | Нативный UI |
| Chaquopy | Android Studio | Высокая | Гибридные проекты |
Подготовка окружения для Buildozer
Buildozer официально рассчитан на Linux; на Windows его запускают через WSL2 (подсистему Windows для Linux) или в виртуальной машине с Ubuntu. Прямой запуск в «чистой» Windows не поддерживается, и попытки обойти это обычно заканчиваются ошибками на этапе компиляции.
Минимальный набор действий в свежей Ubuntu: установить Python, системные зависимости и сам Buildozer через pip. Пример последовательности команд:
sudo apt update
sudo apt install -y python3-pip python3-venv git zip unzip openjdk-17-jdk autoconf libtool pkg-config zlib1g-dev libncurses5-dev libffi-dev libssl-dev
pip3 install --user buildozer cython
Точный список пакетов зависит от версии дистрибутива — сверяйтесь с актуальной документацией Buildozer, так как требования периодически меняются. После установки проверьте, что команда buildozer --version выполняется без ошибок.
⚠️ Внимание: первая сборка скачивает Android SDK, NDK и зависимости — это несколько гигабайтов данных и может занять продолжительное время. Прерывание процесса на середине иногда оставляет повреждённый кэш в папке .buildozer, который придётся удалять вручную.
Пошаговая сборка APK через Buildozer
В корне проекта должен лежать файл main.py — точка входа приложения. Инициализируйте конфигурацию командой buildozer init: рядом появится файл buildozer.spec, в котором задаются название пакета, версия, ориентация экрана и список зависимостей.
Ключевые строки buildozer.spec, которые стоит проверить перед сборкой:
- 📦 requirements — перечислите все библиотеки, например
requirements = python3,kivy,requests; пропущенный модуль даст crash при запуске. - 🏷️ package.name и package.domain — формируют уникальный идентификатор приложения.
- 📐 orientation —
portraitилиlandscape, чтобы приложение не переворачивалось неожиданно. - 🔑 android.permissions — например,
INTERNET, если приложение ходит в сеть.
☑️ Чек-лист перед запуском сборки
Запуск отладочной сборки выполняется одной командой:
buildozer android debugГотовый файл появится в папке bin с именем вида myapp-0.1-arm64-v8a-debug.apk. Установите его на устройство через adb install или скопировав на смартфон и разрешив установку из неизвестных источников.
Сборка на смартфоне через PyDroid3
Если компьютера с Linux под рукой нет, вариант — IDE PyDroid3 прямо на Android-устройстве. Приложение включает редактор, терминал и менеджер pip-пакетов, а платный плагин добавляет экспорт проекта в APK. Это удобно для учебных приложений и прототипов на Kivy или с консольной логикой.
Порядок примерно такой: установите PyDroid3 из магазина приложений, откройте свой скрипт, убедитесь, что он запускается внутри IDE, затем используйте функцию экспорта проекта в APK (доступность зависит от версии и установленных плагинов). Встроенный репозиторий пакетов уже содержит сборки популярных библиотек под Android, что снимает проблему кросс-компиляции.
⚠️ Внимание: APK, собранные на самом устройстве, подписываются отладочным ключом и не подходят для публикации в Google Play без переподписи. Кроме того, набор доступных библиотек ограничен тем, что собрали авторы PyDroid3 — экзотические пакеты с C-расширениями могут отсутствовать.
Типичные ошибки и их решение
Большинство сбоев при конвертации Python в APK относятся к трём категориям: окружение, зависимости и версии SDK/NDK. Разберём самые частые сценарии.
Ошибка компиляции нативной библиотеки. Если в логе фигурирует «error: command failed» на этапе сборки рецепта, вероятная причина — отсутствие рецепта python-for-android для нужной версии пакета. Попробуйте указать более старую стабильную версию библиотеки в requirements или проверить список поддерживаемых рецептов в документации проекта.
Приложение падает сразу после запуска. Подключите устройство к ПК и смотрите лог через adb logcat — в нём будет видно, какого модуля не хватает. Как правило, это пропущенная зависимость в requirements или импорт, который на ПК работает «молча», а под Android требует дополнительных файлов.
Конфликт версий NDK. Buildozer чувствителен к версии Android NDK: слишком новая или слишком старая может ломать сборку. В buildozer.spec версию можно зафиксировать параметром android.ndk; рекомендуемое значение указано в документации к вашей версии Buildozer — не подставляйте случайную версию NDK, сверяйтесь с официальным списком совместимости.
Почему APK получается таким большим
В пакет входит полноценный интерпретатор CPython, скомпилированный под каждую указанную архитектуру (arm64-v8a, armeabi-v7a), плюс стандартная библиотека и все зависимости из requirements. Чтобы уменьшить размер, оставьте в android.archs только arm64-v8a — современные устройства почти все 64-битные — и уберите неиспользуемые пакеты.
Подпись и публикация релизной версии
Отладочный APK подписан тестовым ключом и годится только для проверки на своём устройстве. Для распространения и публикации в магазинах соберите релизную сборку командой buildozer android release и подпишите её собственным ключом.
Ключ создаётся стандартной утилитой keytool из JDK, а подписание выполняется через apksigner — оба инструмента входят в состав Android SDK, который Buildozer уже скачал. Храните файл ключа и пароли в надёжном месте: потеря ключа означает невозможность обновлять приложение под тем же идентификатором пакета.
Также учтите требования магазинов: Google Play в последние годы принимает загрузку в формате AAB (Android App Bundle), а не только APK. Buildozer умеет собирать AAB командой buildozer android release с соответствующей настройкой в buildozer.spec — проверьте актуальные требования площадки перед подготовкой релиза.
Частые вопросы о конвертации Python в APK
Можно ли собрать APK из Python на Windows без Linux?
Напрямую — нет: Buildozer требует Linux-окружение. Рабочие варианты — WSL2 (Ubuntu внутри Windows), виртуальная машина или сборка в облаке. Альтернатива без компьютера — PyDroid3 на самом смартфоне.
Будет ли работать любой Python-скрипт после конвертации?
Нет. Консольные скрипты без GUI потребуют интерфейса (обычно на Kivy), а библиотеки с нативным кодом — готовых рецептов кросс-компиляции. Скрипты, завязанные на файловые пути Windows или системные вызовы ПК, придётся адаптировать.
Почему приложение вылетает при запуске, хотя на ПК работает?
Чаще всего причина в отсутствующей зависимости в requirements файла buildozer.spec или в библиотеке, несовместимой с Android. Диагностируется через adb logcat — в логе видно, на каком импорте происходит сбой.
Насколько медленнее работает Python-приложение по сравнению с нативным?
Точных универсальных цифр нет — всё зависит от задачи. Для интерфейсов и несложной логики разница обычно незаметна пользователю, но ресурсоёмкие вычисления и сложная графика на Python будут ощутимо уступать нативной реализации.
Можно ли опубликовать Python-приложение в Google Play?
Да, при соблюдении требований площадки: релизная сборка, подпись собственным ключом, целевая версия SDK не ниже актуального минимума и, как правило, формат AAB вместо APK. Проверяйте текущие требования в консоли разработчика Google Play.