Android

Experimental Feature

Android support is experimental and may change in future releases.

Wails v3 applications run on Android as native apps: an Android WebView renders the frontend, assets are served in-process through a WebViewAssetLoader backed by the Go asset server (no localhost server, no open ports), and the standard @wailsio/runtime works unchanged — service bindings, events, dialogs and the clipboard route through the Go message processor.

The same main.go builds for desktop and Android. The Go code is compiled as a C shared library (libwails.so, GOOS=android + the NDK toolchain) and loaded by a small Java host. Android-specific behaviour lives in per-platform Go files guarded by //go:build android.

Requirements

• The Android SDK with platform-tools, an SDK platform (API 34), build-tools and the NDK (26.3.x) — wails3 doctor shows what it finds
• A JDK (e.g. OpenJDK 21) for Gradle; set JAVA_HOME if java is not on your PATH
• Go 1.24+ and npm
• ANDROID_HOME (or ANDROID_SDK_ROOT) pointing at the SDK

Install the SDK pieces with the command-line tools:

sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0" \
           "ndk;26.3.11579264" "emulator" \
           "system-images;android-34;google_apis;arm64-v8a"
avdmanager create avd --name wails \
           --package "system-images;android-34;google_apis;arm64-v8a" \
           --device pixel_7

Running on the Emulator

From your project directory:

wails3 task android:run

This boots an emulator if none is running, generates the bindings, builds the frontend, compiles your Go code to libwails.so for the emulator’s ABI, assembles a debug APK with Gradle, then installs and launches it.

Useful companions:

wails3 task android:logs    # stream the app's logcat output

In debug builds the WebView is inspectable from Chrome at chrome://inspect.

Packaging

wails3 task android:package             # production release APK
wails3 task android:deploy-emulator     # install + launch it

Production builds use -tags production,android, are stripped, and compile out the framework’s internal diagnostics. wails3 task android:package:fat builds both arm64-v8a and x86_64 into a single APK.

Signing & release builds

Without a keystore, release builds are signed with the Android debug keystore so they install for testing. To sign with your own keystore, set:

ANDROID_KEYSTORE_FILE=/path/to/release.jks \
ANDROID_KEYSTORE_PASSWORD=... \
ANDROID_KEY_ALIAS=... \
ANDROID_KEY_PASSWORD=... \
  wails3 task android:package

팁

For Play Store uploads, sign a release artifact with your own keystore — set the ANDROID_KEYSTORE_* variables, or open build/android/ in Android Studio and use Build → Generate Signed Bundle / APK to produce an .aab.

Configuration

The frontend drives Android features at runtime through the Android runtime object: Android.Haptics.Vibrate(durationMs), Android.Device.Info(), Android.Toast.Show(message). The package name is controlled by APP_ID in the build tasks.

What works, what doesn’t

Area	Status
WebView + in-process assets (WebViewAssetLoader)	✅
Service bindings, events (both directions)	✅
Message dialogs	✅ AlertDialog with button callbacks
Open file / files dialogs	✅ Storage Access Framework (files imported as cache copies)
Open directory / save file dialogs	❌ Return an error — write inside the app sandbox instead
Clipboard	✅ ClipboardManager
Screens API	✅ WindowMetrics incl. system-bar work area
Lifecycle events (events.Android.*)	✅
Haptics, device info, toast	✅ Android.* runtime API
Window geometry, menus, system tray	Intentional no-ops
Multiple windows	Only the first window is displayed

Porting notes

• Desktop code compiles unchanged under GOOS=android; geometry/menu/tray calls become no-ops because Android apps are fullscreen.
• android implies the linux build tag (Android is a Linux kernel): desktop-Linux-only files need //go:build linux && !android, and at runtime runtime.GOOS is "android".
• Replace save-file and choose-directory dialogs with writes into the app sandbox plus an intent share flow. Open-file dialogs work and import the chosen documents as cache-directory copies, so you get real filesystem paths.
• A real app is always built with CGO_ENABLED=1 and the NDK; the non-cgo path exists only so tooling such as wails3 generate bindings can load the package.
• Design the frontend responsively; the Screens work area excludes the status and navigation bars.