About Winedroid
What is Winedroid?
Winedroid is an Android userspace compatibility layer for macOS and Linux.
The goal is the same spirit as Wine: an APK should run as a first-class desktop
application without starting a full virtual machine or a full Android OS.
The app should not need to know it is running inside Winedroid, just as a
Windows executable does not need to know it is running inside Wine.
This is not a VM, an emulator, or a container-first approach.
The long-term shape is a native desktop runtime that understands APKs, Android
app structure, Android framework expectations, and the services an app needs in
order to launch and behave correctly.
How it works
Android apps ship as APKs (ZIP archives containing DEX bytecode, native
libraries, resources, and a manifest). Winedroid opens the APK directly, without
installing or unpacking Android beneath it:
- APK parsing: reads the manifest, resource table, DEX files, and ELF native libraries.
- ABI selection: determines which native library ABI is appropriate for the host CPU.
- DEX execution: a built-in interpreter executes DEX bytecode opcode-by-opcode. ART can be reused if available.
- Framework shims: calls to Android APIs (Activity, WindowManager, etc.) are intercepted and mapped to host-native equivalents.
- Native bridge: native ARM/x86 libraries are loaded; CPU translation is applied when the guest ABI differs from the host CPU.
What is explicitly out of scope
Winedroid should not become a hidden Android installation with a desktop shell around it. The following are permanently out of scope:
- Hardware or system virtual machines
- Full Android system images as the source of truth
- Container-first Android systems (e.g. running AOSP in Docker)
- adb-installing into a separate Android OS
- Depending on
system_server as the runtime owner
Rating system
The Winedroid AppDB rates app compatibility using the following scale.
Ratings reflect the experience on the most recently tested Winedroid version.
| Rating | Meaning |
|---|
| Platinum |
Runs flawlessly with no issues or workarounds. |
| Gold |
Runs well; minor graphical glitches or trivial workarounds needed. |
| Silver |
Core functionality works but significant issues exist. |
| Bronze |
Launches but crashes or has major functional problems. |
| Barely Works |
Opens and some functionality works, but clearly not usable. |
| Garbage |
Does not run or crashes immediately on launch. |
Project components
- APK / package parser
- Manifest and resource model
- Install / config directory management
- Launch resolver
- Runtime process model
- Host / guest ABI selection
- Native backend branch selection
- Android API and service shims
- Graphics, input, storage, permissions, and lifecycle integration
- DEX / ART execution strategy
- ELF inspection for native libraries
- JNI / native library loading
Development approach
Build trace-first: run the target APK, stop at the first missing primitive,
implement it cleanly, add focused tests, repeat.
It is better to support a small surface correctly than to approximate a broad
surface with confusing behavior.
Engineering rules
- Prioritize correctness
- Keep code atomic: one thing should do one thing
- Avoid clever hacks and dense one-liners
- Prefer readability and simplicity
- Show errors clearly instead of silently trying approximate alternatives
- Make unsupported behavior explicit: fail with a useful message, not a silent fallback
- Design components so future Android services can be added without rewrites
License
Winedroid is free and open-source software.
See the GitHub repository for the current license.
