Приложение на Kivy, которое нормально запускается на компьютере, но падает сразу после старта на Android-смартфоне — самая частая жалоба начинающих разработчиков на этом фреймворке. Причина почти всегда кроется не в коде интерфейса, а в отсутствующих разрешениях, неподдерживаемых модулях Python или ошибках конфигурации сборочного файла buildozer.spec. Проверить это можно за несколько минут, если знать, где искать.
Kivy — это открытый Python-фреймворк для создания кроссплатформенных приложений с графическим интерфейсом. Один и тот же код работает на Windows, Linux, macOS, Android и iOS, что делает Kivy привлекательным выбором для тех, кто хочет писать мобильные приложения на знакомом языке. Ниже разберём установку, структуру проекта, сборку APK и типичные проблемы.
Что такое Kivy и когда его стоит использовать
Kivy основан на OpenGL и использует собственный движок отрисовки интерфейса, поэтому виджеты выглядят одинаково на всех платформах. Фреймворк поддерживает мультитач, жесты, анимации и аппаратное ускорение графики. Для описания интерфейса применяется декларативный язык KV Language, который отделяет разметку от логики приложения.
Фреймворк хорошо подходит для прототипов, внутренних корпоративных инструментов, обучающих программ и приложений с нестандартным интерфейсом. Для проектов, где критичен «нативный» внешний вид элементов управления, Kivy подходит хуже — его виджеты не повторяют системный стиль Android или iOS.
- 🐍 Весь код пишется на Python без необходимости изучать Java или Kotlin.
- 📱 Один кодовый проект собирается под десктоп и мобильные платформы.
- 🎨 Собственный движок рендеринга даёт полный контроль над внешним видом.
- ⚡ Горячая перезагрузка через инструменты вроде KivyMD ускоряет отладку интерфейса.
Установка Kivy и подготовка среды
Перед установкой убедитесь, что у вас актуальная версия Python — Kivy поддерживает современные ветки Python 3, а устаревшие выпуски могут вызывать конфликты зависимостей. Рекомендуется работать в виртуальном окружении, чтобы изолировать пакеты проекта от системных.
python -m venv kivy_env
pip install --upgrade pip
pip install kivy
После установки проверьте работоспособность простым запуском: python -c "import kivy; print(kivy.__version__)". Если команда выводит номер версии без ошибок, среда готова. На Windows иногда требуется обновить драйверы графической подсистемы, так как Kivy зависит от OpenGL.
⚠️ Внимание: не устанавливайте Kivy глобально вместе с другими GUI-библиотеками в одном окружении. Конфликты версий SDL2 и зависимых библиотек — частый источник ошибок вида «Unable to get a window» при запуске.
Создание первого приложения
Минимальное приложение на Kivy состоит из класса, наследующего App, и метода build(), который возвращает корневой виджет. Ниже пример с кнопкой и текстовой меткой:
from kivy.app import App
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.label import Label
class MyApp(App):
def build(self):
layout = BoxLayout(orientation='vertical')
self.label = Label(text='Нажмите кнопку')
btn = Button(text='Старт')
btn.bind(on_press=self.on_press)
layout.add_widget(self.label)
layout.add_widget(btn)
return layout
def on_press(self, instance):
self.label.text = 'Кнопка нажата!'
MyApp().run()
Сохраните файл как main.py и запустите командой python main.py. Откроется окно с вертикальным контейнером: метка сверху, кнопка снизу. При нажатии текст метки изменится — это базовый цикл событий Kivy, на котором строится вся логика взаимодействия.
Интерфейс также можно вынести в отдельный .kv-файл. Kivy автоматически подхватит файл, имя которого совпадает с именем класса приложения (без суффикса App). Такое разделение упрощает поддержку проектов со сложной вёрсткой.
Полезные библиотеки и экосистема
Чистый Kivy предоставляет базовые виджеты, но внешний вид у них минималистичный. Самое популярное расширение — KivyMD, библиотека компонентов в стиле Material Design: карточки, диалоги, навигационные панели, поля ввода с анимацией. Устанавливается командой pip install kivymd.
| Инструмент | Назначение | Установка |
|---|---|---|
| KivyMD | Material Design компоненты | pip install kivymd |
| Buildozer | Сборка APK для Android | pip install buildozer |
| Plyer | Доступ к камере, GPS, уведомлениям | pip install plyer |
| PyInstaller | Сборка EXE для Windows | pip install pyinstaller |
Библиотека Plyer заслуживает отдельного упоминания: она предоставляет единый API к аппаратным функциям устройства — акселерометру, вибрации, уведомлениям, буферу обмена. На десктопе многие вызовы работают как заглушки, поэтому тестировать их нужно на реальном устройстве.
Сборка APK для Android через Buildozer
Сборка мобильного пакета выполняется утилитой Buildozer, которая автоматизирует работу python-for-android. Работает она нативно на Linux; на Windows используйте WSL или виртуальную машину с Ubuntu. Первая сборка занимает заметное время, так как скачиваются Android SDK, NDK и зависимости.
buildozer init
buildozer -v android debug
Команда buildozer init создаёт конфигурационный файл buildozer.spec. В нём обязательно проверьте несколько параметров: title (название приложения), package.name и package.domain (идентификатор пакета), requirements (зависимости, например python3,kivy,kivymd) и android.permissions (разрешения вроде INTERNET или CAMERA).
☑️ Проверка перед сборкой APK
⚠️ Внимание: чисто «питоновские» библиотеки собираются без проблем, но пакеты с компилируемыми C-расширениями (некоторые научные библиотеки, драйверы баз данных) требуют готовых рецептов в python-for-android. Если рецепта нет, сборка завершится ошибкой — проверяйте поддержку заранее в документации проекта.
Типичные ошибки и их решение
Ошибка ModuleNotFoundError на устройстве при рабочем десктопном запуске означает, что модуль не попал в сборку. Откройте buildozer.spec и добавьте его в requirements, затем выполните buildozer android clean и соберите заново — без очистки кеша изменения иногда не подхватываются.
Падение приложения сразу после сплеш-скрина диагностируется через логи. Подключите устройство по USB и выполните buildozer android deploy run logcat — в выводе найдите строку с Python traceback, она укажет конкретную строку кода. Чаще всего причина — обращение к файлу по относительному пути, который на Android указывает в несуществующее место; используйте путь относительно каталога приложения через App.get_running_app().user_data_dir или корректные относительные пути ресурсов.
- 🐛 Чёрный экран при запуске — обычно ошибка в KV-файле или отсутствующий ресурс; смотрите logcat.
- 🔑 Ошибка подписи при установке — удалите старую debug-версию приложения с устройства перед установкой новой.
- 📦 Бесконечная первая сборка — проверьте стабильность сети, Buildozer скачивает SDK и NDK объёмом в несколько гигабайт.
- 🖼️ Не отображаются картинки — убедитесь, что ресурсы перечислены в
source.include_extsконфигурации.
Как ускорить повторные сборки
Buildozer кеширует SDK, NDK и собранные зависимости в папке .buildozer внутри проекта. Не удаляйте её между сборками — повторная компиляция займёт минуты вместо десятков минут. Удалять кеш стоит только при смене версий зависимостей или странных ошибках сборки.
Публикация и дальнейшие шаги
Debug-версия APK подходит только для тестирования. Для публикации в Google Play потребуется релизная сборка (buildozer android release), подписанная вашим ключом, и формат AAB вместо APK — актуальные требования к формату и подписи уточняйте в документации Google Play Console, так как они периодически меняются.
Перед релизом протестируйте приложение на устройствах с разными версиями Android и разрешениями экрана. Kivy масштабирует интерфейс автоматически, но фиксированные размеры шрифтов и отступы в пикселях могут выглядеть иначе — используйте метрики dp и sp вместо жёстких значений.
Часто задаваемые вопросы
Подходит ли Kivy для коммерческих проектов?
Да, Kivy распространяется под свободной лицензией MIT, которая разрешает коммерческое использование без открытия исходного кода. Проверьте только лицензии сторонних библиотек, которые включаете в сборку.
Можно ли собрать APK на Windows без Linux?
Напрямую Buildozer на Windows не работает. Рабочие варианты — подсистема WSL2, виртуальная машина с Ubuntu или облачная сборка через CI-сервисы. Наиболее предсказуемый результат обычно даёт WSL2.
Почему приложение работает медленно на телефоне?
Возможные причины: частая перерисовка виджетов, тяжёлые операции в главном потоке, большие изображения без оптимизации. Вынесите длительные вычисления в отдельные потоки и проверьте, не пересоздаются ли виджеты каждый кадр.
Что лучше: Kivy или нативная разработка?
Зависит от задачи. Kivy выигрывает, когда команда знает Python, нужен кроссплатформенный код и нестандартный интерфейс. Нативная разработка предпочтительнее для приложений, критичных к производительности, размеру пакета и системному внешнему виду.
Как получить доступ к камере и GPS из Kivy?
Используйте библиотеку Plyer — она предоставляет единый Python-интерфейс к аппаратным функциям. Не забудьте добавить соответствующие разрешения в android.permissions файла buildozer.spec и запросить их в коде на Android 6 и новее.