# ApkPy

> ApkPy turns one Python file into a native Android app. You write screens, components, CSS-like styles and callbacks in `writehere.py`; a desktop Previewer runs it, and ApkPy translates it into a Java/XML/Gradle project that builds an APK. No Python runtime ships in the APK, so only a documented subset of Python is translated.

- Install: `pip install apkpy` (Python 3.8-3.13). Building an APK needs a JDK 17-21 and the Android SDK; `apkpy doctor` checks them and `apkpy setup` installs them.
- Latest release: 1.11.0. Package: https://pypi.org/project/apkpy/ - examples and documentation source: https://github.com/apkpy-project/repo-apkpy
- Android only. The app is native Android views (Material components) in generated Java and XML: not a WebView and not an embedded interpreter.
- It is not Kivy, BeeWare/Toga, Flet or python-for-android, and it does not use their packaging (no `buildozer.spec`).
- Only the listed Python is translated. Anything else stops the build with a coded error that names the line (`U2033`). `requests`, `numpy`, `pandas` and other packages cannot run on the phone; ApkPy has its own APIs for HTTP, SQLite, encrypted storage, background jobs and device features, and a `native` block for your own Java.
- Commands: `apkpy start NAME` (new project), `python writehere.py` (Previewer), `apkpy run` (debug APK), `apkpy release` (signed APK, `--aab` for the Play Store), `apkpy build` (Android Studio project), `apkpy doctor`.
- A new project comes with an `AGENTS.md` that tells AI coding assistants how to write ApkPy; `apkpy agents` adds it to an existing project.
- ApkPy does not generate a backend. The core compiler is proprietary; documentation, examples and benchmark programs are public. The maintainer has committed to open-sourcing the core if development stops for good.

## Docs

- [Installation](https://repo-apkpy.pages.dev/getting-started/): install, first project, Previewer and APK
- [Core concepts](https://repo-apkpy.pages.dev/core-concepts/): screens become Activities; components, styles and callbacks
- [Essential API reference](https://repo-apkpy.pages.dev/reference/essential/): exact signatures and callback contracts
- [Compatibility and limits](https://repo-apkpy.pages.dev/compatibility/): the Python that is translated and what stops the build
- [Friendly errors](https://repo-apkpy.pages.dev/friendly-errors/): every `APKPY` code, what it means and the fix
- [Components and layouts](https://repo-apkpy.pages.dev/ui-components/)
- [Themes and styling](https://repo-apkpy.pages.dev/themes-styling/): `Theme()`, the CSS-like `style` string and design tokens
- [Screens and navigation](https://repo-apkpy.pages.dev/navigation/)
- [Data Core](https://repo-apkpy.pages.dev/data-core/): typed SQLite models, CRUD, transactions and migrations
- [Background jobs](https://repo-apkpy.pages.dev/background-jobs/): WorkManager jobs and an offline queue
- [Your own Java](https://repo-apkpy.pages.dev/guides/native/): the way to reach Android APIs ApkPy has no wrapper for
- [Build and release](https://repo-apkpy.pages.dev/build-release/): debug APK, signing, App Bundle

## Comparisons

- [Can ApkPy build this?](https://repo-apkpy.pages.dev/can-apkpy-build-this/): what ApkPy covers for feed, chat, media, maps and notes apps, and what the backend still owns
- [ApkPy vs Kivy, BeeWare and Flet](https://repo-apkpy.pages.dev/apkpy-vs-kivy-flet-beeware/): where each one is the better choice
- [Benchmarks](https://repo-apkpy.pages.dev/benchmark/): one 100-note app measured in the same emulator session - ApkPy 5.37 MiB APK and 2,565 ms cold start, BeeWare/Toga 34.46 MiB and 5,536 ms. One small debug app, not every app. An earlier 590 ms figure measured an app whose list was empty; the page says so.

## Examples

- [Example apps](https://github.com/apkpy-project/repo-apkpy/tree/main/examples): complete `writehere.py` programs, from hello world to an offline queue
- [Showcase](https://repo-apkpy.pages.dev/showcase/): four complete apps, with their source and APKs

## Optional

- [The documentation in one file](https://repo-apkpy.pages.dev/llms-full.txt): the pages above, as plain Markdown
- [API overview](https://repo-apkpy.pages.dev/api-reference/)
- [Native Android features](https://repo-apkpy.pages.dev/native-features/)
- [Native recipes](https://repo-apkpy.pages.dev/guides/native-recipes/): six ready-made Java blocks, each run on a phone
- [NFC tags](https://repo-apkpy.pages.dev/guides/nfc/): verified on a phone for settings, off/on recovery and reader controls; not a full physical read/write certification
- [Contacts](https://repo-apkpy.pages.dev/guides/contacts/): the phone check opened and cancelled the picker; creating and editing contacts has not been tested end to end
- [Previewer versus Android](https://repo-apkpy.pages.dev/preview-android/): where the desktop preview and the phone differ
- [Trust and maturity](https://repo-apkpy.pages.dev/trust-maturity/)
- [Troubleshooting](https://repo-apkpy.pages.dev/troubleshooting/)
- [FAQ](https://repo-apkpy.pages.dev/faq/)
- [Version index](https://repo-apkpy.pages.dev/versions/)
- [Project continuity](https://repo-apkpy.pages.dev/project-continuity/): licence and the open-source commitment