Skip to content

Mobile Builds (Flet / APK)

Whittl can generate mobile apps using Flet (a Python UI framework that targets mobile and desktop) and export them as Android APKs with one click — no Android Studio, no JDK, no Gradle. All build tools download automatically on first use.

Experimental status

Mobile builds work but may need troubleshooting on specific devices. Desktop builds (Windows/Linux PySide6) are stable and production-ready. Mobile is a rougher path — expect to iterate on some device-specific quirks.

Selecting the Mobile (Flet) target

In the chat panel, the Target dropdown defaults to Desktop (PySide6). Switch to Mobile (Flet) for mobile projects.

Once selected:

  • The AI generates Flet code instead of PySide6
  • The Build dialog offers APK export
  • A Device Format selector appears — pick Phone, Tablet, or Custom (width × height)

The device format affects Test Run window dimensions so you see your app at the target device's aspect ratio during development.

Generating a Flet app

Prompt the AI normally:

Make me a mobile recipe app. Users can browse recipes by category,
save favorites, and see a shopping list view. Target Android phones.

The AI generates Flet code using flet 0.28.3 (Whittl's pinned version — see Coding Rules for why).

Test Run on mobile

Click Test Run or F5. The app launches in a window sized to your selected Device Format (400×700 for Phone, etc.), approximating how it'll look on a real device.

What you're seeing is Flet running in "desktop" mode but with mobile dimensions. Actual device rendering differs slightly (touch vs mouse, native controls, etc.) — the APK build is how you get the real thing.

Building an APK

Build (F3) → APK Export tab → Build APK.

First time, Whittl downloads:

  • APK template (Python + Flet + Android runtime) — ~100 MB one-time
  • Signing tools — ~50 MB
  • ADB (Android Debug Bridge) — ~20 MB

Future builds reuse the downloaded toolchain. Total toolchain size on disk: ~200 MB under ~/.whittl/apk_tools/ (Linux) or %LOCALAPPDATA%\Whittl\apk_tools\ (Windows).

Subsequent builds for the same project take 1-3 minutes and produce a signed APK at dist/app-release.apk.

Installing to a device

Three ways to install the APK on an Android device:

Via USB (easiest)

  1. Plug your Android device into your computer via USB
  2. On the device: enable Developer options (Settings → About phone → tap Build number 7 times)
  3. Enable USB debugging (Developer options → USB debugging)
  4. Accept the "Allow USB debugging?" prompt on the device when you plug in
  5. In Whittl's Build dialog: click Install to Device
  6. Whittl uses ADB to push and install the APK

Sideloading

  1. Copy the .apk to the device via email / cloud / USB
  2. On the device, tap the APK file
  3. Enable Install from unknown sources when prompted
  4. Tap Install

Less Dev-mode-requiring than ADB but slower per-iteration.

Play Store distribution

Not supported directly. Google Play requires an AAB (Android App Bundle) format, not APK, plus a signed store-release certificate. Whittl's AAB export is on the roadmap (v2.4+) but not yet shipping.

For now, APKs are for direct distribution / sideloading / internal testing only.

What works on mobile

Flet's capabilities map well to common mobile app patterns:

  • Lists with scroll, often virtualized via ft.ListView
  • Tabs at top or bottom
  • Bottom navigation bar
  • Card layouts for feed-style content
  • Forms with text inputs, dropdowns, checkboxes
  • Local storage via ft.Client.storage (small keys + values)
  • Images via ft.Image
  • Basic animations via ft.AnimatedSwitcher and transitions
  • File picking via ft.FilePicker (with some device caveats)
  • Platform detection via page.platform for conditional logic

What's harder or not working yet

  • Complex file I/O. Android's scoped storage model complicates file access beyond the app's own sandbox. Works for app-private files; getting to user-chosen folders is harder.
  • Background tasks / services. Flet's Python code runs when the app is foreground. Background execution requires native code that Whittl doesn't generate.
  • Native integrations. No built-in way to use platform-specific APIs (notifications, biometric auth, health sensors).
  • Very performance-sensitive UI. A 1000-item list with custom per-row widgets may drop frames. Simple lists fine; complex custom components need optimization.
  • Testing at scale. Each device-OS combination has its own quirks. Budget time for testing on the actual hardware you care about.
  • Black screen on cold launch. Some devices briefly show a black screen between launcher and app. Known issue; no universal fix. Usually cosmetic.

Auto-fix for mobile code

Whittl's auto-fix includes 13 Flet-specific rules that catch common mobile generation mistakes:

  • ft.icons → ft.Icons (API renamed for mobile)
  • ft.colors → ft.Colors
  • page.dialog → page.open() / page.close() (deprecated API)
  • padding= removed from Column/Row (Flet requires Container for padding)
  • String alignments → enum forms ("center" → ft.MainAxisAlignment.CENTER)
  • Hallucinated control names caught (ft.FloatingButton → ft.FloatingActionButton)
  • Missing ft.app(target=...) at module tail

These fire on every Flet generation; you don't have to think about them.

Device format reference

Format Dimensions Ratio Use case
Phone 400 × 700 4:7 Standard Android phones
Tablet 800 × 1200 2:3 Tablets and foldable-unfolded state
Custom user-set any Specific device targeting

Flet version pin

Whittl pins flet[all]==0.28.3. This version is known to work across the APK template and generation pipeline. Attempting to upgrade Flet manually breaks things. The Flet upgrade strategy is on the roadmap but deferred until Flet 1.0 stabilizes.

Don't pip upgrade Flet yourself

If you run pip install flet --upgrade in Whittl's terminal, the APK build will fail because the template expects 0.28.3. Revert by reinstalling: pip install flet[all]==0.28.3.

Troubleshooting mobile builds

"ADB device not found"

Device isn't in USB debugging mode, or the USB driver isn't installed.

  • Check USB debugging is enabled (Developer options on device)
  • On Windows, install Google's USB driver if Windows doesn't auto-detect your device
  • Try a different USB cable (some cables are charge-only)

APK installs but crashes on launch

Usually a missing asset or import. Check:

  • Your app uses assets/ for all resources (not an absolute path like /Users/you/file.png)
  • Any pip packages you import are Flet-mobile-compatible (some aren't — numpy and PIL have native deps that may or may not bundle)
  • The Flet version used to generate the app matches 0.28.3

APK file is huge (100+ MB)

Mobile APKs bundle the Python runtime and all dependencies. Typical Flet APKs are 40-80 MB; adding numpy / opencv pushes to 120+ MB. Usually fine — modern devices handle it.

Device shows "App not installed"

Usually means the APK's signature conflicts with a previously-installed version:

# Uninstall the old version first
adb uninstall com.yourapp.package

Then reinstall.

What's next