📱 Mobile & Desktop Capabilities in PyDataUI
PyDataUI gives you pure-Python cross-platform application development across Web, Mobile (iOS & Android), and Desktop (macOS, Windows, Linux) with zero Swift or Kotlin code required.
👉 Looking for Native Offline Mobile Architecture?
See Native Offline & Standalone Architecture for bundling assets inside APK/IPA packages with 100% offline standalone operation and in-process JNI dispatch.
🏗️ Architecture Overview
Rather than rewriting your UI in platform-specific native UI primitives (like React Native / Flutter bridge overhead), PyDataUI uses an optimized Server-Driven Webview Architecture across three tiers:
flowchart TD
Python["PyDataUI Application (100% Python)"] --> Core["Reactive Engine (HTMX + Tailwind CSS)"]
Core --> Tier1["Tier 1: Instant PWA\n(Zero build, iOS/Android home screen)"]
Core --> Tier2["Tier 2: Capacitor Native Shell\n(.apk & Xcode iOS project)"]
Core --> Tier3["Tier 3: Lightweight Desktop Shell\n(Tauri 2.0 / Native App Mode)"]
| Strategy | Target | Setup Effort | Build Required? | App Store Ready? |
|---|---|---|---|---|
| Mobile Simulator & Preview | Browser (iPhone/Android bezel) | ⚡ Instant (0 sec) | ❌ No Xcode/Android Studio | 📱 Live Web Preview |
| Instant PWA | iOS Safari & Android Chrome | ⚡ Instant (0 sec) | ❌ No | 🟡 Add to Home Screen |
| Capacitor Headless CLI | Android .apk & iOS Native |
2 minutes | ❌ Headless CLI (No IDE) | ✅ Yes (Google Play / App Store) |
| Lightweight Desktop Window | macOS, Windows, Linux | ⚡ Instant (0 sec) | ❌ No | 🖥️ Desktop window mode |
| Tauri 2.0 Native Shell | macOS .dmg, Win .msi, Linux .deb |
2 minutes | 🦀 Rust / Cargo | ✅ Yes |
⚡ Zero-IDE Mobile Development (No Xcode & No Android Studio)
PyDataUI eliminates the need to install or open heavy IDEs like Xcode or Android Studio just to develop, preview, or test mobile apps.
💡 The PyDataUI Fast-Mobile Loop
- Develop in Python: Edit your UI components and reactive state in Python with instant auto-reload.
- Preview in Browser: Test inside realistic device bezels (iPhone 15 Pro, Pixel 8, iPad Mini) directly in your browser.
- Scan QR Code: Scan with your physical phone camera to test on real hardware over Wi-Fi.
- Finalize & Install: Install immediately as a PWA or compile an Android
.apkdirectly from the terminal without opening Android Studio.
1. Launch the In-Browser Mobile Device Simulator
Run your app with the mobile simulator enabled:
or via the run command:- Navigate to
http://localhost:8000/_pdu/preview. - Realistic Phone Chassis: Switch between iPhone 15 Pro, Google Pixel 8, iPhone SE, and iPad Mini.
- Rotate Device: One-click toggle between Portrait and Landscape orientation.
- Fast Reload: Instantly refresh the embedded app frame when updating Python code.
- Real Phone QR Code: Click Test on Real Phone to display a QR code containing your local LAN IP or tunnel URL (
share=True). Scan with your phone's camera to run the app directly on your physical device.
2. Headless Android APK Build & Direct Device Install
When you have finalized your app and want an installable Android APK, build it directly from your terminal:
# Compile 100% offline standalone Android APK (React Native Parity, default):
pydataui mobile build --platform android
# Compile for live Wi-Fi development / hot reload:
pydataui mobile build --platform android --live-sync
# Connect to a remote production API:
pydataui mobile build --platform android --server-url https://api.mycompany.com
# Directly install to connected Android device over USB/Wi-Fi via ADB:
pydataui mobile install --platform android
The compiled APK is output to android/app/build/outputs/apk/debug/app-debug.apk and ./app-debug.apk.
📘 Deep Dive Guide: See Native Offline & Standalone Mobile Architecture for full details on asset bundling, in-process JNI dispatch, and eliminating
net::ERR_CONNECTION_REFUSED.
📱 Tier 1: Instant Mobile PWA (Zero Setup)
Every PyDataUI application includes automatic Progressive Web App (PWA) support enabled by default.
Features
- Mobile Viewport Optimization: Rendered with
viewport-fit=cover, disabling unintended zoom glitches while respecting iOS notch & home indicator safe-areas. - Standalone Mode: Runs without Safari/Chrome browser address bars or navigation toolbars.
- Auto-generated Web Manifest: Served at
/_pdu/manifest.json. - Service Worker: Cache and offline lifecycle handled at
/_pdu/sw.js.
How to use:
from pydataui import App
from pydataui.components import Container, Heading, Button
app = App(
title="Inventory Tracker",
pwa=True, # Enabled by default
pwa_name="Inventory Pro", # Name on mobile home screen
pwa_short_name="Inventory"
)
@app.page("/")
def home():
return Container(
Heading("Mobile Ready App", level=1),
Button("Tap Action", variant="primary", full_width=True),
padding="md"
)
if __name__ == "__main__":
app.run()
- Run your app:
python app.py - Open the URL in Safari (iOS) or Chrome (Android).
- Tap Share ➡️ Add to Home Screen.
- The app launches full-screen directly from the phone's home screen.
📦 Tier 2: Capacitor Mobile Shell (iOS & Android Native)
To package your PyDataUI application as a native .apk or submit it to the Apple App Store, PyDataUI provides 1-command scaffolding via Capacitor.
1. Initialize Mobile Project
Run the following CLI command in your project directory:
pydataui mobile init --app-name "My Data App" --app-id "com.company.dataapp" --server-url "http://localhost:8000"
This automatically generates:
- capacitor.config.json configured with your live server URL and mobile preferences.
- package.json with @capacitor/core and @capacitor/cli.
- public/index.html fallback bridge.
2. Add Mobile Platforms
3. Build & Run on Device / Simulator
# Sync web configuration to native projects
pydataui mobile sync
# Open in Xcode or Android Studio
pydataui mobile run ios
pydataui mobile run android
From Xcode or Android Studio, click Run to launch in the simulator, or archive for TestFlight / Google Play production release.
📋 Native Build Requirements & Prerequisites (Android & iOS)
To compile native mobile packages (.apk / .aab for Android or .ipa / .xcarchive for iOS), your development machine must satisfy specific platform toolchain prerequisites.
📊 Platform Requirements Comparison
| Requirement | 🤖 Android Native (.apk / .aab) |
🍎 iOS Native (.ipa / Xcode) |
⚡ Instant PWA (Recommended) |
|---|---|---|---|
| Host OS | macOS, Linux, or Windows | macOS required | Any OS |
| JDK (Java) | Java 17 LTS (or 21 LTS) ⚠️ Do NOT use Java 25+ |
❌ None | ❌ None |
| Node.js & npm | Node 18+ or 20+ LTS | Node 18+ or 20+ LTS | ❌ None |
| Build Core | Gradle 8.x + Android SDK | Xcode 15+ & xcodebuild |
❌ None |
| Package Manager | npm (@capacitor/android) |
CocoaPods or SPM (@capacitor/ios) |
❌ None |
| Developer Account | Google Play Console ($25 once, for store) | Apple ID (Free for device, $99/yr for store) | ❌ None |
| Build Time | ~1 to 2 minutes | ~1 to 3 minutes | Instant (0 sec) |
🤖 Android Native Build Requirements
Android compilation is powered by Gradle and the Android SDK.
1. Java Development Kit (JDK 17 LTS Required)
Gradle and the Android Gradle Plugin (AGP) require an LTS Java runtime.
[!CAUTION] Do NOT install Java 25 or higher. Gradle 8.x will fail with:
Unsupported class file major version 69.
Always use Java 17 (Recommended by Google) or Java 21.
# Install Eclipse Temurin Java 17 LTS
brew install --cask temurin@17
# Set JAVA_HOME in current session & ~/.zshrc
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 17)' >> ~/.zshrc
# Verify installation
java -version
# Expected: openjdk version "17.0.x"
2. Android SDK & Environment Variables
If you build locally via Gradle, you must provide the Android SDK:
- Option A: Android Studio (Easiest)
- Download & install Android Studio.
- In Settings ➡️ SDK Manager, ensure the following are checked:
- Android SDK Platform 34 (or latest)
- Android SDK Build-Tools (34.0.0+)
- Android SDK Command-line Tools
- Option B: Headless Command-line Tools
- Download
commandlinetools-mac/linuxfrom Google's Android developer site. - Accept licenses:
yes | sdkmanager --licenses
Required Environment Variables:
Add the following to your ~/.zshrc or ~/.bashrc:
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
3. Capacitor Android Plugin
In your PyDataUI project directory:
npm install @capacitor/core @capacitor/cli @capacitor/android
pydataui mobile build --platform android
The resulting debug APK is generated at:
🍎 iOS Native Build Requirements
iOS apps must be compiled on macOS using Apple's official Xcode toolchain.
1. System & Hardware
- macOS Sonoma (14+) or macOS Ventura (13+).
- Mac hardware: Apple Silicon (M1/M2/M3/M4) or Intel Mac.
2. Xcode & Command Line Tools
- Install Xcode 15+ or 16+ from the Mac App Store.
- Install command line developer tools:
- Accept the Xcode license:
3. CocoaPods (Dependency Manager)
Capacitor iOS projects require CocoaPods to link native iOS frameworks:
4. Capacitor iOS Plugin
In your PyDataUI project directory:
5. Code Signing & Apple Developer Account
Apple requires code signing for every executable on physical iOS devices:
- Free Personal Apple ID: Allows deploying directly to your personal connected iPhone for 7 days via USB without paying the $99/year developer fee.
- Apple Developer Program ($99/year): Mandatory if distributing via TestFlight or the public Apple App Store.
To sign your app: 1. Open the generated iOS project:
2. In Xcode, click App in the sidebar ➡️ Signing & Capabilities. 3. Under Team, select your Apple ID account. 4. Connect your iPhone via USB, select it as the target device, and press Cmd + R to run.🛠️ Common Native Build Issues & Solutions
| Error Message | Root Cause | Solution |
|---|---|---|
Unsupported class file major version 69 |
Installed Java 25+, which Gradle 8.x does not support. | Install Java 17 LTS: brew install --cask temurin@17 and set export JAVA_HOME=$(/usr/libexec/java_home -v 17). |
The operation couldn’t be completed. Unable to locate a Java Runtime. |
Java is missing or unlinked on macOS. | Run brew install --cask temurin@17 or use the zero-Java PWA alternative. |
SDK location not found. Define a location with an ANDROID_HOME environment variable |
Android SDK directory is not set. | Add export ANDROID_HOME=$HOME/Library/Android/sdk to your shell profile, or create android/local.properties with sdk.dir=/Users/YOUR_USER/Library/Android/sdk. |
Signing for "App" requires a development team |
Xcode cannot sign without an Apple Developer Team. | Open Xcode (npx cap open ios), go to Signing & Capabilities, and select your personal Apple ID under "Team". |
CocoaPods could not find compatible versions |
Pods lockfile or repo out of date. | Run cd ios/App && pod repo update && pod install. |
💡 Recommendation: Skip Heavy SDKs with Instant PWA
If you do not want to manage 10GB+ of Xcode, Android Studio, and Java toolchains:
1. Runpydataui run app.py (or pydataui mobile preview app.py).
2. Scan the QR code on your iPhone or Android.
3. Tap Add to Home Screen.
4. You get an app icon, standalone full-screen view, and offline caching with zero build tools!
🖥️ Tier 3: Desktop Shell & Standalone Window
Instant Desktop Window (Zero Dependency)
You can launch any PyDataUI app in a standalone native desktop window without installing Node.js or Rust:
or programmatically in Python:from pydataui import App
app = App(title="Desktop Analytics")
# ... routes ...
if __name__ == "__main__":
app.run(desktop=True)
Tauri 2.0 High-Performance Native Desktop Shell
For distribution as a compiled macOS .dmg / Windows .msi / Linux .deb executable:
1. Initialize Tauri Shell
This generates an optimizedsrc-tauri directory with:
- Cargo.toml and Tauri 2.0 dependencies.
- tauri.conf.json configured to embed PyDataUI.
- Polling mechanism to await Python server readiness before showing the window.
2. Run in Dev Mode
3. Build Production Native Bundles
The compiled platform binary is generated insrc-tauri/target/release/bundle/.
💡 Best Practices for Mobile UI in PyDataUI
-
Enable Mobile Mode Preset:
Automatically activates Starletteapp = App(title="Mobile App", mobile_mode=True) # Or via environment variable: # PYDATAUI_MOBILE_MODE=1GZipMiddleware, strips web PWA service-worker boilerplate, and activates dirty-tracked component subtree updates. -
In-Process JNI Bridge (Chaquopy): In Capacitor mobile apps, PyDataUI supports zero-socket native execution via
PyDataUIWebViewInterceptorandpydataui.shell.bridge.dispatch_in_process. The native Android webview catches all/_pdu/*calls before hitting the network stack and executes the ASGI app in-process in memory, cutting latency by 5–15 ms per request and eliminating Uvicorn daemon threads. -
Use Responsive Containers:
- Touch-friendly tap targets:
Use
size="lg"orfull_width=Trueon buttons for easy mobile tapping. - Bottom navigation bar:
Combine
Flexwith Tailwind classesfixed bottom-0 left-0 right-0 z-50 bg-background border-tfor mobile tab navigation.