Waydroid tips: windows, translation, and shared directories

Source and license: this article includes a compilation and adaptation of Ivon Huang’s “Waydroid Tips: Fixing No Network or Unresponsive Touch, Registering the Play Store, and Installing an ARM Translator”. The original and the portions of this article adapted from it are provided under CC BY-SA 4.0, requiring attribution and sharing under the same license. This article selects and adapts some sections and adds command examples, safety notes, and version limitations; distinguish the original author’s experience from this site’s additional notes. This license notice was added on 2026-10-09. It applies only to the source material identified above and its adaptations, does not extend that license to other content on this site, and does not imply the original author’s endorsement of this site.

Scope and prerequisites#

Commands and output are generic examples. Kernel, image, package, and service versions affect specific behavior; check the documentation for the versions you use as you read.

Before modifying containers, images, mounts, or firewalls, back up Android data and stop the relevant sessions; examples involving deletion or forced stops may lose data. Manage NixOS system and user-environment configuration through Nix. The general Linux sections using apt/pacman, writing directly to /etc, or installing with pip do not apply to a NixOS host. Rebuild build, test, and switch operations and post-startup functional verification are separate stages.

The Chinese source for this article was compiled from Ivon Huang’s original article and retains its Traditional Chinese wording. Some commands were missing from the original clipping; the necessary examples are supplied below using official interfaces. Historical observations are not guaranteed to apply to current versions.

Window and desktop integration#

Clicking another app’s icon on the Linux desktop, rather than its icon on the Android home screen, launches that app in a separate, fixed-size window with its own entry in the Linux desktop taskbar. Only one app can still run at a time; they cannot run simultaneously. Switching app windows pauses the other app: a game’s screen freezes, for example, or Youtube stops playing. These apps cannot use the notification shade, and pressing Back automatically closes the app window without fully stopping the app.

If you enable “multi-window mode” (see below), the Waydroid icon disappears from the Linux desktop. Apps launched from the Linux desktop then have resizable windows and can run simultaneously without pausing when you switch apps. Clicking the close button or pressing Back closes the app window without fully stopping the app.

Waydroid’s text clipboard integration and input-method integration are separate features. You can install a suitable input method in Android; you are not limited to Gboard. Availability of the host’s input method depends on graphics/input integration.

2. Waydroid commands#

While Waydroid is running, Android system data is stored in ~/.local/share/waydroid/data/, system images are in /var/lib/waydroid, and app icons are in ~/.local/share/applications/ Start the Waydroid container service Stop the Waydroid container service How do you update Android? Use this command to stop the container and download the latest images: Open the Waydroid main interface from the command line View system error messages Waydroid can install APKs from the command line Use the following command to enter the Android shell, which has built-in root privileges and can run Android shell commands. Wyadroid automatically enables ADB debugging after startup. You can start ADB on the Linux host and pair with it. Find the IP address in Androi system settings → About phone. How do you enable developer options? Open Android system settings → About phone → Build number and tap it five times. Developer options then appear under Android system settings → System (normally, follow the on-screen instructions and tap the build number 7 times).

3. Change Waydroid’s language to Chinese#

In Android, open Settings → System → Languages, add Chinese, and drag it to the top of the list.

After changing the language, Android’s clock should automatically synchronize using the time zone and network time.

4. Fix Waydroid’s lack of network connectivity#

Try opening the firewall ports. The firewall varies by distribution and may be Firewalld, UFW, iptables, or another option. UFW commands for Ubuntu: Firewalld commands for Fedora: Then restart Waydroid: If that still does not work, Waydroid’s network may conflict with Docker’s. There is no need to stop Docker; simply modify Waydroid’s network configuration file: LXC_USE_NFT is a network-script variable. Check the currently installed package first; do not append it to the LXC config as though it were a valid option: Restarting Waydroid should then resolve the issue.

5. Register the device for the Google Play Store#

Waydroid is built on LineageOS. You should have downloaded an image with built-in GMS services when installing Waydroid. However, a third-party ROM cannot access the Google Play Store unless its device is registered with Google.

1. Enter the Android shell
2. Run the following command to obtain a long code: the GMS device ID. If there is no output, check that Waydroid has a working network connection.
3. Go to Google’s device registration page and enter the code
4. Wait for the service to reflect the registration status before restarting. Self-certification does not guarantee that all Play Store or integrity-check problems will disappear.

6. Install an ARM translator to fix app crashes#

Computers with an ARM architecture can skip this step. Most computers use x86, while many mobile games provide only ARM APKs, so software is needed to translate ARM instructions into x86 instructions. How can you tell whether an app is ARM-only? Without an ARM translator installed by default, Google Play may not show certain apps. Alternatively, after installing an APK, use Package Manager to check whether the app includes /lib/x86_64 libraries. If it has only ARM libraries, it will crash on launch and needs an ARM translator. Available ARM translators include Intel’s “libhoudini” and Google’s “libndk”; both are proprietary software. Some community advice suggests choosing by CPU vendor, but that is not a proven performance guarantee. Image versions, instruction sets, and individual apps especially need real-world testing. Some apps may work with one translator but not the other, so test different combinations. Do not install both ARM translators at the same time. To switch to the other one, run the script below, select Remove to remove the old translator, and then install the new one.

sudo apt install lzip
cd ~
git clone https://github.com/casualsnek/waydroid_script
cd waydroid_script
python3 -m venv venv
venv/bin/pip install -r requirements.txt
cd ~/waydroid_script

5. Run the script, use Space to select libhoudini or libndk, then press Enter to install the ARM translator. ARM translators are tied strictly to their Android version and must not be mixed across versions.
6. Restart Waydroid
7. Sometimes Google Play still does not show apps for architectures other than x86. In that case, find an ARM APK on ApkMirror, install it, and check whether it launches correctly.
8. If an ARM translator has trouble running a particular app, try reporting it in Waydroid’s GitHub issues and see whether a community patch is available. For example, a player created this script to fix a login crash in the game Blue Archive.
9. You may need to reinstall the ARM translator after updating the Waydroid system.

Multi-window mode is useful for apps that need a portrait orientation and also allows multiple apps to run simultaneously. 10. Use the following command to set the option to true, enabling Waydroid’s multi-window mode so multiple apps can run on the same screen. 11. It is recommended to enable “Enable freeform windows” in Android’s developer options. 12. The Waydroid icon then disappears from the Linux application menu, leaving only the app icons (you can still open the Android main interface with waydroid show-full-ui). 13. After launching, apps behave more like native Linux applications, with freely resizable windows. 14. Some apps may still start full-screen. Press F11 to switch to windowed mode; press F11 again to return to full-screen. 15. When an app enters full-screen mode, other apps pause, preventing two or more apps from running simultaneously. It is best to keep apps windowed. 16. Android’s multitasking interface is unavailable in multi-window mode. To stop an app completely, you must open Android Settings → Apps and force-stop it.

The original author recorded some window-management limitations in Android 13: certain apps break when resized or cannot be resized at all. If problems occur, turn this feature off: Android also has its own built-in “freeform” window feature, launched from the multitasking screen. This allows apps to resize freely only within the Waydroid window.

8. Run duplicate apps and multiple apps simultaneously#

Waydroid is not designed to run multiple instances, so you cannot use separate instances to log in to two accounts in the same app at once. However, you can use Shelter’s work-profile feature to run two copies of an app in a single Android system. By design, Waydroid adds an icon for each Android app to the Linux desktop’s application list after its APK is installed. Launching apps from these icons lets you run multiple apps, but “multi-window mode” must be enabled for two or more apps to run “simultaneously.” What if an app refuses to run windowed in multi-window mode and insists on full-screen? Make use of your desktop environment’s virtual desktops. GNOME, KDE Plasma, Hyprland, and COSMIC all provide virtual desktops, also called workspaces. If an app fills the entire current virtual desktop when launched, switch to the next virtual desktop before launching another app. Each workspace can then run its own app.

9. Share a directory between Linux and Waydroid#

After Waydroid starts, its data is in ~/.local/share/waydroid/data/media/0/. This is Android’s internal storage and requires root privileges to access. With KDE Dolphin file manager 6.0 or later, you can request root privileges to access Android’s files. Alternatively, access files by mounting a directory with ordinary permissions. To avoid affecting other files, I recommend creating a dedicated shared folder named WaydroidShared on both sides. Use mount to mount Linux’s ~/WaydroidShared onto the WaydroidShared folder inside Waydroid: You can also transfer files wirelessly with ADB commands. Find Waydroid’s IP address under Android system settings → About.

adb connect Waydroid的IP:5555
adb push "本機目錄" "Android的目錄"

Some apps require Wifi to be enabled before downloading; otherwise they assume you have only mobile data. Give them what they expect by enabling fake wifi. Use waydroid app list to find an app’s package name. Configure it with the following syntax:

waydroid prop set persist.waydroid.fake_wifi "套件名稱"

For example, enable simulated Wifi for the Mihon manga reader, also enable downloads without Wifi in the app’s settings, then restart the container: Use waydroid app list to find an app’s package name. Some apps do not recognize mouse clicks and require fake touch:

waydroid prop set persist.waydroid.fake_touch "套件名稱"

For example, enable simulated touch for the Fate/Go game, then restart the container: If an app still does not respond to clicks after simulated touch is enabled, consider another approach, such as controlling Waydroid with Scrcpy Install an app such as Rotation Control to force Waydroid’s screen orientation. Waydroid may not be able to switch to a portrait screen resolution unless you use a Linux tablet with a rotatable screen.

13. Adjust app volume#

Open Android system settings → Sound to adjust the volume. Physical keys cannot control volume inside the Android container, so install a separate volume-control app. Add it as a widget on the Android home screen, or use Sound Quick Settings to add a volume-control button to Android’s notification shade. The Linux desktop’s volume-control panel, such as pavucontrol, can mute Waydroid’s output separately. Waydroid can also access the Linux microphone, so Android apps should be able to record audio normally. Microphone volume can likewise be adjusted in pavucontrol. If multiple apps are running and you want to mute a particular app, the MixedAudio feature in ShizuTools is recommended. Android’s multitasking screen has a screenshot button for individual apps. There is no Linux-side shortcut to trigger the Android hardware-key screenshot action, so use a Linux screenshot tool. Alternatively, install Screenshot Tile to add a native screenshot button to Android’s notification shade.

15. Prevent crashes caused by app detection of root or an emulator#

Sometimes an app refuses to install or crashes because it considers your device unsafe, rather than because of ARM translation. Waydroid cannot pass even the most basic Play Integrity API level, so some apps refuse to run. Apps requiring DRM also cannot play their content. The solution is more complicated: you might install Magisk to hide root or spoof the device model. See Avoiding Root Detection in Waydroid and Installing Magisk and LSPosed Waydroid’s Android app icons are located at ~/.local/share/applications/waydroid.* Write a script to delete them after Waydroid closes. If using a Wayland session is inconvenient, use a nested Wayland session instead. See Launching Waydroid with Weston on a Linux X11 Desktop Without a Wayland Desktop At the time of Nvidia driver 575, the original author recorded that Waydroid supported only Intel and AMD graphics cards, not Nvidia. To run Waydroid on an Nvidia card anyway, you had to use software rendering. In this mode, performance was too poor for gaming. Note: someone created a waydroid-choose-gpu.sh script to select the GPU Waydroid uses. It appears to address graphics issues in Nvidia + Intel configurations by forcing Intel rendering when Nvidia is the primary GPU. However, Waydroid relies on the desktop compositor; using the same GPU may reduce cross-device dma-buf compatibility problems, although it is not a universal requirement. The script therefore appears to work only in Intel + AMD configurations. 17. Initialize Waydroid 18. Edit the configuration file 19. Add the following content to enable SwiftShader 20. Apply the changes 21. Restart Waydroid

Supplying the missing commands from the clipping#

sudo systemctl start waydroid-container
waydroid session start
waydroid show-full-ui
waydroid log
waydroid app install /path/to/example.apk
sudo waydroid shell
waydroid prop set persist.waydroid.multi_windows true
waydroid session stop

Before sharing a dedicated directory, create it on both sides and confirm permissions and the scope of the data; do not share your entire home directory with Android. Stop the session, make a backup, then bind-mount the dedicated directory and check that the mapping is visible inside the container.

mkdir -p ~/WaydroidShared
# Android 資料目錄的建立/權限按現場使用者和映像核對
sudo mount --bind ~/WaydroidShared ~/.local/share/waydroid/data/media/0/WaydroidShared

SwiftShader’s startup-time configuration is in /var/lib/waydroid/waydroid.cfg, under [properties]:

[properties]
ro.hardware.gralloc=default
ro.hardware.egl=swiftshader

First stop the active session, then run sudo waydroid upgrade --offline as appropriate for the installed version and restart the container. This operation may rebuild generated properties; back up custom settings.

Verification sources#

Ivon Huang’s original article.

Waydroid official installation instructions.

Waydroid official command documentation.

Waydroid upstream source.

Official property documentation.