Ошибка ModuleNotFoundError: No module named 'kivy' при первом запуске проекта — самая частая причина, по которой разработчики застревают на старте работы с Kivy: пакет установлен в другое виртуальное окружение или конфликтует с версией Python. Фреймворк Kivy позволяет писать кроссплатформенные приложения на Python и собирать их в APK для Android, но цепочка инструментов требует аккуратной настройки.
В этой статье разберём, как работает связка Python + Kivy + Android: от установки и создания интерфейса до сборки APK-файла через Buildozer и решения типичных проблем. Материал подойдёт тем, кто уже знает основы Python и хочет перенести свои скрипты на смартфон.
Что такое Kivy и зачем он нужен
Kivy — открытый фреймворк на Python для создания приложений с графическим интерфейсом. Его ключевая особенность — кроссплатформенность: один и тот же код работает на Windows, Linux, macOS, Android и iOS. Интерфейс строится на виджетах и рендерится через OpenGL, поэтому приложения выглядят одинаково на разных устройствах.
Для мобильной разработки Kivy привлекателен тем, что не требует знания Java или Kotlin. Вам достаточно Python и понимания базовых концепций: виджеты, layouts, события. Однако стоит понимать ограничения: Kivy-приложения обычно занимают больше места, чем нативные, а доступ к некоторым системным API Android требует дополнительных библиотек вроде PyJNIus.
Альтернативы Kivy для Python на Android — BeeWare и Chaquopy, но именно Kivy имеет самое развитое сообщество и зрелый инструментарий сборки.
Установка Kivy и подготовка окружения
Перед установкой убедитесь, что у вас актуальная версия Python — Kivy поддерживает современные ветки Python 3. Рекомендуется работать в виртуальном окружении, чтобы избежать конфликтов зависимостей. Создайте его командой python -m venv kivy_env и активируйте.
Установка выполняется через pip:
pip install kivyПосле установки проверьте работоспособность минимальным примером — окном с надписью. Если окно открылось, фреймворк готов к работе. На Windows иногда требуются дополнительные зависимости (kivy_deps), которые pip подтягивает автоматически при установке свежих версий.
⚠️ Внимание: не устанавливайте Kivy глобально и в окружение одновременно — импорт может подхватить не ту копию пакета. Проверить, откуда загружается модуль, можно через kivy.__file__.
Создание первого приложения
Минимальное приложение на Kivy состоит из класса, унаследованного от App, и метода build(), возвращающего корневой виджет. Вот пример с кнопкой:
from kivy.app import App
from kivy.uix.button import Button
class MyApp(App):
def build(self):
return Button(text='Привет, Android!')
MyApp().run()
Для более сложных интерфейсов используется язык разметки KV — декларативный способ описывать виджеты, их свойства и связи. Разметку можно держать в отдельном файле .kv, что отделяет логику от представления и упрощает поддержку проекта.
Основные строительные блоки интерфейса:
- 📦 Layouts — контейнеры BoxLayout, GridLayout, FloatLayout для размещения элементов
- 🔘 Виджеты — кнопки, метки, поля ввода, переключатели
- 🎨 Свойства — реактивные атрибуты, автоматически обновляющие интерфейс
- 📱 ScreenManager — навигация между экранами приложения
Сборка APK через Buildozer
Чтобы превратить Python-код в установочный файл Android, используется Buildozer — инструмент, автоматизирующий работу python-for-android. Важный нюанс: Buildozer официально работает на Linux. На Windows применяют WSL (подсистему Linux) или виртуальную машину, на macOS поддержка ограничена.
Порядок действий такой. Установите Buildozer через pip, перейдите в папку проекта и инициализируйте конфигурацию:
pip install buildozer
buildozer init
Появится файл buildozer.spec — в нём задаются имя приложения, пакет, версия, требуемые разрешения (например, доступ к интернету) и зависимости. После настройки запустите сборку:
buildozer android debugПервая сборка занимает заметное время: Buildozer скачивает Android SDK, NDK и собирает интерпретатор Python под мобильную архитектуру. Последующие сборки проходят быстрее за счёт кэша. Готовый APK появится в папке bin/.
☑️ Перед первой сборкой APK
⚠️ Внимание: точка входа в проект обязательно должна называться main.py. Если главный файл назван иначе, Buildozer не найдёт его, и сборка завершится ошибкой или приложение не запустится.
Типичные ошибки и их решения
Чаще всего проблемы возникают не в коде, а на этапе сборки. Приложение, отлично работающее на ПК, может падать на телефоне сразу после старта. Чтобы увидеть причину, подключите устройство по USB и смотрите логи через adb logcat — там будет Python-traceback.
Типовые ситуации:
- 💥 Crash при запуске — обычно не хватает зависимости в
requirementsфайла buildozer.spec; добавьте пакет и пересоберите - 🐢 Зависание сборки — первая загрузка SDK/NDK может прерываться из-за сети; повторный запуск продолжит с того же места
- 📵 Нет доступа к функциям телефона — не объявлены разрешения в spec-файле или не запрошены в рантайме на новых версиях Android
- 🔤 Проблемы с кириллицей — стандартный шрифт может не содержать нужных глифов; подключите TTF-шрифт с поддержкой русского языка
Если приложение использует сторонние библиотеки с C-расширениями (например, numpy), убедитесь, что для них существует рецепт в python-for-android — чисто питоновские пакеты собираются без проблем, а компилируемые требуют поддержки со стороны сборочной системы.
Как посмотреть логи падающего приложения
Подключите телефон по USB с включённой отладкой (режим разработчика). Выполните команду adb logcat | grep python — в выводе будет полный traceback с указанием строки, вызвавшей ошибку. Без этого шага диагностика падений на устройстве практически невозможна.
Сравнение подходов: Kivy и альтернативы
Выбор инструмента зависит от задачи. Ниже — ориентировочное сравнение популярных способов запуска Python на Android; конкретные характеристики могут меняться от версии к версии, поэтому перед стартом проекта сверяйтесь с актуальной документацией.
| Инструмент | Язык UI | Сложность сборки | Кому подходит |
|---|---|---|---|
| Kivy | Python + KV | Средняя (Buildozer) | Кроссплатформенные приложения |
| BeeWare | Нативные виджеты | Средняя | Приложения с нативным видом |
| Chaquopy | Android SDK (Kotlin/Java) | Высокая | Встраивание Python в нативное приложение |
| Pydroid 3 | Запуск скриптов | Низкая | Обучение и эксперименты на телефоне |
Если цель — быстро запускать скрипты на смартфоне без сборки APK, проще всего подойдёт Pydroid 3 или Termux. Для полноценного приложения с публикацией в каталогах разумнее Kivy: только он даёт зрелую цепочку «код → APK → релиз» целиком на Python.
Публикация и дальнейшие шаги
Debug-сборка подписана тестовым ключом и годится только для проверки на своём устройстве. Для распространения соберите релизный вариант командой buildozer android release и подпишите APK собственным ключом. Требования к подписи и формату загрузки в магазины приложений периодически меняются — актуальные условия уточняйте в документации выбранной площадки.
Перед релизом протестируйте приложение на устройствах с разными версиями Android и разрешениями экрана. Kivy масштабирует интерфейс автоматически, но фиксированные размеры шрифтов и отступы могут выглядеть иначе на маленьких экранах — используйте dp-метрики вместо пикселей.
Часто задаваемые вопросы
Можно ли писать Kivy-приложения прямо на телефоне?
Да, через приложения вроде Pydroid 3 можно редактировать и запускать Kivy-код на самом Android-устройстве. Однако полноценная сборка APK всё равно потребует компьютер с Linux-окружением.
Почему Buildozer не работает на Windows?
Buildozer рассчитан на Linux-инструментарий сборки. На Windows используйте WSL — подсистему Linux, в которой Buildozer устанавливается и работает так же, как на обычном дистрибутиве.
Приложение падает на телефоне, но работает на ПК. Что делать?
Подключите устройство по USB и снимите логи через adb logcat. Наиболее вероятные причины — отсутствующая в buildozer.spec зависимость или библиотека, несовместимая с мобильной сборкой Python.
Нужно ли знать Java для Kivy-разработки?
Для большинства задач — нет. Знание Java или Kotlin может понадобиться только при работе со специфическими системными API Android через PyJNIus, но базовые приложения пишутся целиком на Python.
Насколько велик размер готового APK?
Размер зависит от подключённых зависимостей и архитектур, под которые собирается пакет. Kivy-приложение включает интерпретатор Python, поэтому обычно заметно крупнее аналогичного нативного. Уменьшить объём помогает сборка под конкретные архитектуры и исключение лишних библиотек.