# Waydroid

Waydroid is a container-based approach to boot a full Android system on a regular GNU/Linux system like Ubuntu.

## Overview

Waydroid uses Linux namespaces (user, pid, uts, net, mount, ipc) to run a full Android system in a container and provide Android applications on any GNU/Linux-based platform.

The Android inside the container has direct access to needed hardwares.

The Android runtime environment ships with a minimal customized Android system image based on the [LineageOS](https://lineageos.org). The used image is currently based on Android 13.

## Index

### Usage

{% content-ref url="/pages/-MiqooCqYSCO4quxrEfa" %}
[Install Instructions](/usage/install-on-desktops)
{% endcontent-ref %}

{% content-ref url="/pages/-MiYHgF90eAl\_ZbsWUjb" %}
[Install and Run Android Applications](/usage/install-and-run-android-applications)
{% endcontent-ref %}

{% content-ref url="/pages/-MisgOCSCxT0\_edk04yu" %}
[Waydroid command line options](/usage/waydroid-command-line-options)
{% endcontent-ref %}

{% content-ref url="/pages/-MknoF7N\_hT2pIDy9Mtf" %}
[Waydroid Prop Options](/usage/waydroid-prop-options)
{% endcontent-ref %}

### FAQ

{% content-ref url="/pages/i0wGYwHnt9fZSAGcMqIf" %}
[Google Play Certification](/faq/google-play-certification)
{% endcontent-ref %}

{% content-ref url="/pages/-MjQnjSbUHB8yZFfN1t\_" %}
[Disable On-Screen Keyboard](/faq/disable-on-screen-keyboard)
{% endcontent-ref %}

{% content-ref url="/pages/Vr15fKR3hVa2m37eXWIO" %}
[Disable Touch Sounds](/faq/disable-touch-sounds)
{% endcontent-ref %}

{% content-ref url="/pages/6DqDz713fj8RVrkN1aa9" %}
[Community Projects We Like](/faq/community-projects-we-like)
{% endcontent-ref %}

{% content-ref url="/pages/KcHFOV3UI3fEIdMORiYX" %}
[Get Waydroid to work through a VM](/faq/get-waydroid-to-work-through-a-vm)
{% endcontent-ref %}

{% content-ref url="/pages/EDAH4FhdatxaDzy3suwf" %}
[Using ADB with Waydroid](/faq/using-adb-with-waydroid)
{% endcontent-ref %}

{% content-ref url="/pages/FA4IWEXPGieRos9Z4amV" %}
[Setting up Waydroid only Sessions](/faq/setting-up-waydroid-only-sessions)
{% endcontent-ref %}

{% content-ref url="/pages/V9aZIQVsprItoQ0Z3YDQ" %}
[Setting up a shared folder](/faq/setting-up-a-shared-folder)
{% endcontent-ref %}

{% content-ref url="/pages/AHE0I8hOEuuFe5auwH4z" %}
[Color correction in Mutter](/faq/color-correction-in-mutter)
{% endcontent-ref %}

{% content-ref url="/pages/zAToVLGrcBiPYmUoZP8D" %}
[Backup/Restore apps and data](/faq/backup-restore-apps-and-data)
{% endcontent-ref %}

{% content-ref url="/pages/MAslYADnaJLqrW8IzSB0" %}
[Using custom Waydroid images](/faq/using-custom-waydroid-images)
{% endcontent-ref %}

{% content-ref url="<https://github.com/waydroid/docs/blob/master/faq/install-system-app.md>" %}
<https://github.com/waydroid/docs/blob/master/faq/install-system-app.md>
{% endcontent-ref %}

### Development

{% content-ref url="/pages/-MiYZqVH0PdAbUWK5maT" %}
[Compile Waydroid - Lineage OS based images](/development/compile-waydroid-lineage-os-based-images)
{% endcontent-ref %}

{% content-ref url="/pages/-MiqcWTO-Dum4MX10zdL" %}
[Manual Patch Resolution](/development/manual-patch-resolution)
{% endcontent-ref %}

### Help improve this page

You may help improve this page by opening a pull request to the [docs repo](https://github.com/waydroid/docs)

### Licensing

{% content-ref url="<https://github.com/waydroid/docs/blob/master/licensing/licensing.md>" %}
<https://github.com/waydroid/docs/blob/master/licensing/licensing.md>
{% endcontent-ref %}

## Reporting bugs

If you have found an issue with Waydroid, please [file a bug](https://github.com/waydroid/waydroid/issues/new/choose).

## Get in Touch

If you want to get in contact with the developers please feel free to join the *Waydroid* groups in

* [Matrix](https://matrix.to/#/#waydroid:matrix.org)
* [Telegram](https://t.me/WayDroid)
* [Reddit](https://www.reddit.com/r/waydroid/)

## Credits

We'd like to say thanks to all these great teams & projects: @Anbox @LineageOS @Android-x86 @spurv @LXC and many others, for you still lead the way for Open Innovation in Linux and the Android community.


# Install Instructions

## Install Instructions

### Arch Linux

Some of our friends have started putting together all the install instructions for Arch over on the arch wiki:

{% embed url="<https://wiki.archlinux.org/title/Waydroid>" %}

### Postmarket OS

Thanks to the Postmarket community, you can also find instructions and troubleshooting tips on their wiki:

{% embed url="<https://wiki.postmarketos.org/wiki/Waydroid>" %}

### Zorin OS

User @Aman9das has put together a detailed guide for installing Waydroid on Zorin OS:

{% embed url="<https://github.com/Aman9das/Waydroid_Setup_Guide>" %}

### Sailfish OS

A few of the contributors to sailfishos-open have put together a resource for installing Waydroid on the OS:

{% embed url="<https://github.com/sailfishos-open/waydroid>" %}

### Fedora

Waydroid can be installed from the official package repository.

```bash
sudo dnf install waydroid
```

After installing, launch Waydroid from the applications menu and proceed with the initialization by pasting these URLs in the OTA fields:

System OTA: `https://ota.waydro.id/system`

Vendor OTA: `https://ota.waydro.id/vendor`

#### Silverblue/Kinoite/...

The same instructions apply to the Fedora Immutable variants, but you should use `rpm-ostree` instead of `dnf`

```bash
rpm-ostree install waydroid
```

### openSUSE Tumbleweed/Slowroll

User @runa-chin had created a detailed guide about installing Waydroid on openSUSE Tumbleweed or openSUSE Slowroll:

{% embed url="<https://github.com/waydroid/waydroid/discussions/1463>" %}

### KISS Linux

User Mederim has come up with a guide for getting Waydroid on KISS Linux:

{% embed url="<https://github.com/Mederim/kiss-waydroid>" %}

### Void Linux

Waydroid can be installed from the official package repository; also check `/usr/share/doc/waydroid/README.voidlinux` after installation for further instructions!

```bash
sudo xbps-install -S waydroid
```

### Debian/Ubuntu and derivatives

> \[!NOTE] Make sure you have Wayland Session enabled (Ubuntu 22.04+)

{% embed url="<https://linuxconfig.org/how-to-enable-disable-wayland-on-ubuntu-22-04-desktop>" %}

#### Make sure Waydroid is available in your distribution:

* **Debian 14+ & Ubuntu 26.10+ and distros which are based on those**

  Waydroid is available in the official repository. → Skip the repository setup and go directly to [Installation](#install-waydroid).
* **Debian 13 (Trixie)**

  Waydroid is available in the `backports` repository. Enable backports by editing your apt source file, then update apt. → Skip the third-party repo and go directly to [Installation](#install-waydroid).
* **Other Debian/Ubuntu releases (older versions)**

  You must enable the **third-party** Waydroid repository. First, install prerequisites and add the official Waydroid repo:

  ```bash
  sudo apt install curl ca-certificates -y
  curl -s https://repo.waydro.id | sudo bash
  ```

  > If the script fails to detect your distribution, append `-s <DISTRO>`. Supported values: **mantic**, **focal**, **jammy**, **kinetic**, **lunar**, **noble**, **plucky**, **questing**, **bookworm**, **bullseye**, **trixie**, **sid**
* **Droidian**

  Skip all the steps above and go directly to [Installation](#install-waydroid) (or follow Droidian-specific instructions).
* **Ubuntu Touch**

  Waydroid is installed by default. Nothing else is needed.

#### Install Waydroid

```bash
sudo apt update
sudo apt install waydroid -y
```

Then start Waydroid from the applications menu.

### NixOS

NixOS community has a wiki page for WayDroid:

{% embed url="<https://wiki.nixos.org/wiki/Waydroid>" %}

## Troubleshooting

### Manually Starting Waydroid

To start Waydroid without systemctl, you need to follow a few simple steps

**Start the container first:**

```bash
sudo waydroid container start
```

**And in a new terminal tab, start the waydroid session (without** ***sudo*****):**

```bash
waydroid session start
```

After that starts and you see "Android with user 0 is ready", it is safe to launch an app from the applications menu, or

### Launch Waydroid In Full-Screen Mode:

*(This can be run while Waydroid is running, or used to start it in full-screen mode)*

```bash
waydroid show-full-ui
```

### Launch Waydroid In Multi-Window Mode:

First we need to set the property while a Waydroid session is running:

```bash
waydroid prop set persist.waydroid.multi_windows true
```

After that, we can restart the session:

```
waydroid session stop
```

Then we are ready to launch an app, and it will start in multi-window mode

### Reinstalling Waydroid

Sometimes things don't go as planned and you need to remove it all and start over. To do that, follow the steps below:

First, make sure you have stopped the session and containers:

```bash
waydroid session stop
sudo waydroid container stop
```

Then it is safe to remove Waydroid. For example, on debian or ubuntu:

```bash
sudo apt remove waydroid
```

After you removed Waydroid, reboot.

Then once logged back in, we need to do a little cleanup:

```bash
sudo rm -rf /var/lib/waydroid /home/.waydroid ~/waydroid ~/.share/waydroid ~/.local/share/applications/*aydroid* ~/.local/share/waydroid
```

Then you can follow the install instructions again.


# Install and Run Android Applications

Waydroid is able to perform a few various operations found by using the `waydroid app -h` command:

```bash
usage: waydroid app [-h] {install,remove,launch,list} ...

optional arguments:
  -h, --help            show this help message and exit

subaction:
  {install,remove,launch,list}
    install             push a single package to the container and install it
    remove              remove single app package from the container
    launch              start single application
    list                list installed applications
```

You can install Android applications with:

```bash
waydroid app install xyz.apk
```

Then you can launch the application through your desktop Application Menu.

If you know the Android package name of the app (`com.xxx.yyy`) you can also use the commandline with:

```bash
waydroid app launch com.foo.bar
```

The apk files you will sometimes find on the internet tend to only have arm support, and will therefore not work on x86\_64.

You may want to install [F-Droid](https://f-droid.org) to get applications graphically. Or use the Play Store if you installed a GAPPS image.


# Waydroid command line options

Waydroid offers a number of command line arguments and options in order to work with the various parts of the program.

## Usage

`waydroid [-h] [-V] [-l LOG] [--details-to-stdout] [-v] [-q]`

## optional arguments

* `-h`, `--help` : Show this help message and exit
* `-V`, `--version` : Show program's version number and exit
* `-l LOG`, `--log LOG` : Path to log file (default: /var/lib/waydroid)
* `--details-to-stdout` : Print details (e.g. build output) to stdout, instead of writing to the log
* `-v`, `--verbose` : Write even more to the logfiles (this may reduce performance)
* `-q`, `--quiet` : Do not output any log messages
* `-f` : Force options (used with init commands)
* `-i LOCATION` : Initialize from specified location (default: `/usr/share/waydroid-extra/images`) *\*used with init action\**

## Actions

You can use the following actions with the waydroid tool

* `status` : Quick check for the waydroid
* `log` : Follow the waydroid logfile
* `init` : Set up waydroid specific configs and install images
* `upgrade` : Upgrade images
* `session` : Session controller
* `container` : Container controller
* `app` : Applications controller (see: [Install and Run Android Applications](/usage/install-and-run-android-applications))
* `prop` : Android properties controller
* `show-full-ui` : Show android full screen in window
* `shell` : Run remote shell command
* `logcat` : Show Android's logcat

## Init Options

Usage: `waydroid init [-h] [-i IMAGES_PATH] [-f] [-c SYSTEM_CHANNEL] [-v VENDOR_CHANNEL] [-r ROM_TYPE] [-s SYSTEM_TYPE]`

* `-h` | `--help` : Show this help message and exit
* `-i IMAGES_PATH` | `--images_path IMAGES_PATH` : Custom path to waydroid images (default in /var/lib/waydroid/images)
* `-f` | `--force` : Used when resetting or using custom images added to /usr/share/waydroid-extra/images
* `-c SYSTEM_CHANNEL` | `--system_channel SYSTEM_CHANNEL` : Custom system channel (options: OTA channel URL; default is Official OTA server)
* `-v VENDOR_CHANNEL` | `--vendor_channel VENDOR_CHANNEL` : Custom vendor channel (options: OTA channel URL; default is Official OTA server)
* `-r ROM_TYPE` | `--rom_type ROM_TYPE` : Rom type (options: "lineage", "bliss" or OTA channel URL; default is LineageOS)
* `-s SYSTEM_TYPE` | `--system_type SYSTEM_TYPE` : System type (options: VANILLA, FOSS or GAPPS; default is VANILLA)

## Log Options

Usage: `waydroid log [-h] [-n LINES] [-c]`

* `-h` | `--help` : Show this help message and exit
* `-n LINES` | `--lines LINES` : Count of initial output lines
* `-c` | `--clear` : Clear the log

## Container Options

Usage: `waydroid container [-h] {start,stop,restart,freeze,unfreeze} ...`

* `-h` | `--help` : Show this help message and exit

#### Subaction:

`{start,stop,restart,freeze,unfreeze}`

* `start` : start container
* `stop` : stop container
* `restart` : restart container
* `freeze` : freeze container
* `unfreeze` : unfreeze container

## Session Options

Usage: `waydroid session [-h] {start,stop} ...`

* `-h` | `--help` : Show this help message and exit

#### Subaction:

* `{start,stop}` : start start session stop start session

## Examples

* `log`:

  ```bash
  waydroid log > ~/waydroid-log.txt
  ```
* `logcat`:

  ```bash
  sudo waydroid logcat > ~/waydroid-logcat.tx
  ```
* Initialize for test builds:\
  Create the folder: `usr/share/waydroid-extra/images` and extract your customized images there.\
  First, you need to do a little cleanup (if this fails, reboot and try again):

  ```bash
  sudo rm -rf /var/lib/waydroid /home/.waydroid ~/waydroid
  ```

  Then run:

  ```bash
  sudo waydroid init -f
  sudo waydroid init
  ```

  Or, if you have your test images in another location (ex: \~/Downloads/test\_build/), then run:

  ```bash
  sudo waydroid init -f
  sudo waydroid init -i ~/Downloads/test_build
  ```


# Waydroid Prop Options

Waydroid uses various properties in order to tell the underlying Android system how to behave in a few places. To do this, we use the `waydroid prop set <property> <value>` command. To unset a prop, `waydroid prop set <property> ""`. Most settings require restarting the waydroid session to apply.

### Waydroid behaviour

* **waydroid prop set persist.waydroid.multi\_windows** true/false (bool) Enables/Disables window integration with the desktop
* **waydroid prop set persist.waydroid.height\_padding** 0-9999 (int) Adjust height padding
* **waydroid prop set persist.waydroid.width\_padding** 0-9999 (int) Adjust width padding
* **waydroid prop set persist.waydroid.width** 0-9999 (int) Used for user to override desired resolution
* **waydroid prop set persist.waydroid.height** 0-9999 (int) Used for user to override desired resolution
* **waydroid prop set persist.waydroid.suspend** true/false (bool, default: true on kernel 4.9 and later) Let the Waydroid container sleep (after the display timeout) when no apps are active
* **waydroid prop set persist.waydroid.uevent** true/false (bool, default: false) Allow android direct access to hotplugged devices
* **waydroid prop set persist.waydroid.reverse\_scrolling** true/false (\bool default: false) Invert the direction of scrolling

#### App behaviour

* **waydroid prop set persist.waydroid.fake\_touch** (string, 91 character limit) Comma separated list of package names for which mouse inputs should be interpreted as touch inputs instead. Supports wildcards with `*`. For example, set this to `"com.rovio.*"` to match all games by Rovio.
* **waydroid prop set persist.waydroid.fake\_wifi** (string, 91 character limit) Comma separated list of package names for which the system will always appear as if connected to wifi. Supports wildcards with `*`. For example, set this to `"com.gameloft.*"` to match all games by Gameloft.

### Debug

* **waydroid prop set persist.waydroid.no\_presentation** true/false (bool) Disables the wp\_presentation protocol
* **waydroid prop set persist.waydroid.invert\_colors** true/false (bool) Swaps the color space from RGBA to BGRA
* **waydroid prop set persist.waydroid.cursor\_on\_subsurface** true/false (bool) Draw the cursor on a subsurface, rather than on the cursor surface
* **waydroid prop set persist.waydroid.cursor\_force\_shm** true/false (bool) Always submit wl\_shm buffers for the cursor surface
* **waydroid prop set persist.waydroid.no\_background\_subsurface** true/false (bool) Do not submit a black background subsurface
* **waydroid prop set persist.waydroid.use\_subsurface** true/false (\bool) Submit overlayed subsurfaces rather than letting Android compose the stack


# Google Play Certification

When launching waydroid with GAPPS for the first time you will be notified that the device is not certified for **Google Play Protect**. You can follow the instructions on screen to self certify your device, or here's a shortcut:

* Open a Terminal
* Run the following command:

```sh
sudo waydroid shell -- sh -c "sqlite3 /data/data/*/*/gservices.db 'select value from main where name = \"android_id\";'"
```

* Use the string of numbers printed by the command to register the device on your Google Account at <https://www.google.com/android/uncertified>
* Give the Google services some minutes to reflect the change, then restart waydroid with:

```sh
waydroid session stop
```


# Disable On-Screen Keyboard

Stop on-screen keyboard from popping up while typing

Waydroid by default shows the Android virtual keyboard when selecting an input field. To disable that, and only use the physical keyboard, turn off the following setting: `Settings > System > Languages & input > Physical keyboard > Use on-screen keyboard`


# Disable Touch Sounds

How to disable Android touch feedback sounds in Waydroid

Waydroid may produce audio click sounds when tapping the screen due to Android's touch feedback system. This can sometimes interfere with app audio.

To disable touch sounds, go to:

`Settings > Sound > Advanced > Other sounds and vibrations > Touch sounds` (toggle off)


# Community Projects We Like

Here is a list of a few of the projects that work with Waydroid to add some more features/functionality.

#### Waydroid Script

User @casualsnek has put together a tool that will help Waydroid users install OpenGapps, root with Magisk, and install libndk-translation libraries for ARM emulation.

{% embed url="<https://github.com/casualsnek/waydroid_script>" %}

#### Droid-NDK-Extractor

User @sickcodes has put together a script that will download (using Android-Generic Projects emu-x86 repo) and extract the libndk-translation libs from Google's Android Studio emulator images.

{% embed url="<https://github.com/sickcodes/Droid-NDK-Extractor>" %}

#### Darth Wadr

User @aditya24raj has put together an alternative install script using bash that helps to automatically perform the needed steps for installing Waydroid without hastle.

{% embed url="<https://github.com/aditya24raj/darth_waydr>" %}

#### Waydroid BigLinux

The folks at BigLinux have some configuration tools that help run Waydroid on that platform:

{% embed url="<https://github.com/biglinux/waydroid-biglinux>" %}


# Get Waydroid to work through a VM

This also applies to any unsupported GPU's as well (like nVidia)

You can force Waydroid to run without GPU acceleration by modifying the waydroid configuration file:

```
nano /var/lib/waydroid/waydroid.cfg
```

Add the following lines in the `[properties]` section:

```
ro.hardware.gralloc=default
ro.hardware.egl=swiftshader
```

Apply the configuration with:

```js
sudo waydroid upgrade -o
```

### Qemu

Qemu is the only VM known to have working 3d acceleration (possibly crosvm too).

Qemu needs to have virtio-gpu setup with 3d graphics acceleration enabled for both virtio-gpu and the display (Ie. Spice, SDL etc.). Using EGL-headless (useful for dedicated VM servers) will also work with waydroid these will work on any qemu which has 3d acceleration built for it.

Another method to use gpu passthrough on the VM, this will work on any virtual machine software that supports it.


# Using ADB with Waydroid

Grab waydroid IP address from **Android Settings-> About**

And start adb:

```
adb connect <IP>:5555
```


# Setting up Waydroid only Sessions

For some projects, you might want to have Linux only for backend or maintenance related tasks, while using the Waydroid full-screen UI as the main interface.

This document will review changes required for setting up wayland sessions for a full-screen Waydroid experience.

## Setting Up

In order to set this up, you will need to create a few files, depending on your default wayland session manager.

Please create the files detailed by their contents using the contents below

### Cage

`/usr/share/wayland-sessions/waydroid.desktop` contents:

```
[Desktop Entry]
Name=WayDroid
Comment=Android OS in a container
Exec=/usr/bin/cage waydroid show-full-ui
Type=Application
```

### Mutter

`/usr/bin/mutter-session.sh` contents (make sure to mark the file as executable):

```
#!/bin/sh
mutter --wayland &
sleep 5
export DISPLAY=:1
waydroid show-full-ui
```

`/usr/share/wayland-sessions/mutter.desktop` contents:

```
[Desktop Entry]
Name=WayDroid on Mutter
Comment=Android OS in a container
Exec=/usr/bin/mutter-session.sh
Type=Application
```

### Weston

`~/.config/weston.ini` contents:

```
[libinput]
enable-tap=true

[shell]
panel-position=none
```

`/usr/bin/waydroid-session.sh` contents:

```
#!/bin/sh
weston &
sleep 3
konsole -e waydroid show-full-ui
```

`/usr/share/wayland-sessions/waydroid.desktop` contents:

```
[Desktop Entry]
Name=WayDroid on Weston
Comment=Android OS in a container
Exec=/usr/bin/waydroid-session.sh
Type=Application
```

### Wayfire

`/usr/bin/wayfire-session.sh` contents:

```
#!/bin/sh
wayfire &
export DISPLAY=:1
sleep 5
waydroid show-full-ui
```

`/usr/share/wayland-sessions/wayfire.desktop` contents:

```
[Desktop Entry] 
Name=waydroid on Wayfire 
Comment=Android OS in a container 
Exec=/usr/bin/wayfire-session.sh
Type=Application
```


# Setting up a shared folder

User @wachidadinugroho has worked out the details on how to setup a shared folder to be used between Waydroid and your host filesystem.

Setting up a shared folder will allow the user to copy/paste files from the host and they appear inside waydroid/android.\
\
`sudo mount --bind <source> ~/.local/share/waydroid/data/media/0/<target>`

Then verify that the target folder exists:

`sudo ls ~/.local/share/waydroid/data/media/0/`\
\
**Examples:**

```
 sudo mount --bind ~/Documents ~/.local/share/waydroid/data/media/0/Documents 
 sudo mount --bind ~/Downloads ~/.local/share/waydroid/data/media/0/Download 
 sudo mount --bind ~/Music ~/.local/share/waydroid/data/media/0/Music 
 sudo mount --bind ~/Pictures ~/.local/share/waydroid/data/media/0/Pictures 
 sudo mount --bind ~/Videos ~/.local/share/waydroid/data/media/0/Movies
```

You can also make your own custom mount point to cater to your needs.

## Mount the internal storage

Alternatively you can directly mount the internal storage to a target folder on your host, using bindfs to set your user as the owners of all mounted files (original owner permissions are preserved in the source folder).

```
sudo mkdir /mnt/waydroid
sudo bindfs --mirror=$(id -u) ~/.local/share/waydroid/data/media/0 /mnt/waydroid
```


# Color correction in Mutter

Correct the colors when using a Mutter shell

### Using Patched Mutter

If you're using the patched Mutter version from the Waydroid repo with the color inversion patch (or Gnome 42 or higher), or mutter-rounded, then Waydroid should display properly.

### Using Standard Mutter

If you aren't able to install the patched version of Mutter, you can run this in the host shell:

```bash
waydroid prop set persist.waydroid.invert_colors true
```

Note that with this option enabled, you should not use this in combination with multi-window mode.

If you want to do it from inside the Android shell:

```bash
settings put secure accessibility_display_inversion_enabled 1
```

Running this inside the Android shell will correct all of the colors except for the boot animation.


# Backup/Restore apps and data

Backup and restore apps and data using Seedvault

[Seedvault](https://github.com/seedvault-app/seedvault) can be used to taking backup and restore it. It is preinstalled on Waydroid.

## Backup:

### 1. Choose Seedvault as backup provider

Go to Settings > System > Backup > Change backup provider. And choose Seedvault,

![](/files/FX939yNOxrslDScZ4eLw)

### 2. Note down passphrase

A passphrase is shown. This is used for encryption. It will be required for restoration.

![](/files/IYQzf0HSatvycYtCqIsi)

### 3. Take backup

Tap on 'Backup' from three-dots menu.

![](/files/hAOuAkdNLrJXqKjUvqTU)

Successfully backed up. The backup data will be at `~/.local/share/waydroid/data/media/0/.SeedVaultAndroidBackup`

## Restore

### 1. Copy backup contents

Copy the `.SeedVaultAndroidBackup` to `~/.local/share/waydroid/data/media/0/`

### 2. Start restore activity.

You need to run `am start com.stevesoltys.seedvault/.restore.RestoreActivity` in the shell in order to start the restoration activity. You can do this either on `waydroid shell` or `adb shell`.

![](/files/B19149fE6I5OtFkbNZuv)

You will be asked to choose storage.

### 2. Enter passphrase for decryption

You need to enter the passphrased there was shown while setting up Seedvault

![](/files/A8T1w3gl947bCmbduht2)

### 3. Restore

Click on restore.


# Using custom Waydroid images

In order to get custom images to work on Waydroid, there are just a couple extra steps needed.

First, download the images (e.g. x86\_64 gapps system and mainline vendor) manually [from sourceforge](https://sourceforge.net/projects/waydroid/files/images/) or use your custom built `system.img` and `vendor.img` produced from following the [Compile Instructions](/development/compile-waydroid-lineage-os-based-images#how-to-build).

Then copy/move them to the following folder:

```
/etc/waydroid-extra/images/
```

`/usr/share/waydroid-extra/images/` used to be the previously preferred path before `waydroid --version` 1.3.3 (it still is perfectly valid however right now as well).

An example of setting up from downloaded sourceforce zips (assuming terminal open in the directory where they were downloaded):

```sh
sudo mkdir -p /etc/waydroid-extra/images
sudo unzip lineage-*-system.zip -d /etc/waydroid-extra/images
sudo unzip lineage-*-vendor.zip -d /etc/waydroid-extra/images
rm lineage-*-system.zip lineage-*-vendor.zip
```

Then we need to re-init Waydroid in order for it to use the custom images:

```sh
sudo waydroid init -f
```


# Compile Waydroid - Lineage OS based images

## Getting started

To get started with Android/LineageOS, you'll need to get familiar with [Repo](https://source.android.com/source/using-repo.html) and its [Git workflow](https://source.android.com/docs/setup/create/coding-tasks).

### Initializing

To initialize your local repository using the LineageOS trees, use a command like this:

```
repo init -u https://github.com/LineageOS/android.git -b lineage-20.0 --git-lfs
repo sync build/make
```

Then we grab the Waydroid local\_manifests

```
wget -O - https://raw.githubusercontent.com/waydroid/android_vendor_waydroid/lineage-20/manifest_scripts/generate-manifest.sh | bash
```

### Syncing

Then to sync up:

```
repo sync
```

Then we setup the local build environment:

```
. build/envsetup.sh
```

### Patching

After that is complete, we apply the Waydroid patches:

```
apply-waydroid-patches
```

## How to build

Please see the [LineageOS Wiki](https://wiki.lineageos.org/) for building environment setup.

### Waydroid AOSP Lunch Options:

```
lineage_waydroid_arm-userdebug
lineage_waydroid_arm64-userdebug
lineage_waydroid_arm64_only-userdebug
lineage_waydroid_x86-userdebug
lineage_waydroid_x86_64-userdebug
```

### Waydroid Build Commands:

```
. build/envsetup.sh
lunch lineage_waydroid_arm64-userdebug
make systemimage -j$(nproc --all)
make vendorimage -j$(nproc --all)
```

### Image Generation From Sparse Image:

The output of the AOSP build system is an "Android Sparse Image"; we need raw fileystems instead. Starting from the `lineage-20.0` branch, the output is already a raw image.

On earlier branches, from the same terminal where you just built a system and a vendor image, run:

```
simg2img $OUT/system.img ~/system.img
simg2img $OUT/vendor.img ~/vendor.img
```

to obtain your target raw images at \~/system.img and \~/vendor.img

### HALIUM images

The official Waydroid OTA channels provide special vendor images for HALIUM systems. These are regular vendor images that are stripped of the Mesa GPU drivers in order to save space. To build a HALIUM image the same way as the official images, simply disable the `TARGET_USE_MESA` option before compiling:

```
export TARGET_USE_MESA=false
```

## Troubleshooting

### Local Manifest:

To manually regenerate the local\_manifests, we also have added a function to do so

```
waydroid-generate-manifest
```

After doing that you will want to resync (this will wipe out any local changes, so make sure you save your work to a different branch)

### Patch Conflicts:

See [Manual Patch Resolution](/development/manual-patch-resolution)


# Manual Patch Resolution

At the end of the `apply-waydroid-patches` script, it will show the results of how each patch applied. You will want to then make a copy of all the results of the patch scripts (Copy and paste the contents of the terminal output into a Notepad or text document). Each of the patches applied either resulted in "Applying", "Already applied", or "Conflicts". The only ones we want to pay attention to here are the "Conflicts", but only half of them.

Some of the patches have duplicates for different vendor setups. So you will sometimes get results that look like this:

```
Conflicts          system/core/0015-init-don-t-bail-out-even-no-SELinux-domain-defined.patch
Applying          system/core/0015-init-don-t-bail-out-even-no-SELinux-domain-defined.patch 0
```

Notice how the one starting with "0015-" failed, but the patch resolution it found was applied correctly? If that happened on your vendor setup, you can ignore that patch. But if you only see one patch that had a "Conflicts", that will need to be applied and fixed.

First, you apply the patch manually:

```
git am "<SOURCES_ROOT>/vendor/extra/waydroid-patches/base-patches-<AOSP_SDK_VERSION>/<PATCH_PATH>"
```

You can expect that to fail, but it's crucial to the next step. Next you patch the file again, but using the "patch" command

```
patch -p1 < "<SOURCES_ROOT>/vendor/extra/waydroid-patches/base-patches-<AOSP_SDK_VERSION>/<PATCH_PATH>"
```

This will generate the .orig & .rej files to help narrow down what you need to fix. Once the conflicting parts (what's in the .rej files) are resolved, delete the .rej & .orig files, then stage the files:

```
git add -A
```

Then we can continue the staged git am commit from the first step:

```
git am --continue
```

After applying the patch(s) to your local project folder, remember to generate the patch needed to resolve that conflict:

```
git format-patch -1
```

Then copy the patch to the appropriate vendor folder for the conflict. Any conflicts that happened from the base patches themselves should go to the vendor/extra/waydroid-patches/roms-patches/your-rom-name/ folder Example:

```
cp system/core/0001-init-don-t-bail-out-even-no-SELinux-domain-defined.patch vendor/extra/waydroid-patches/roms-patches/__YourRomName__/system/core/0015-init-don-t-bail-out-even-no-SELinux-domain-defined.patch
```


# Compile Waydroid - Using Android-Generic Project

For those not aware, [Android-Generic Project](https://android-generic.github.io), which is best known for bringing PC targets to AOSP based ROMs, also supports Waydroid targets too.

This documentation will go over how to use AG for compiling Waydroid.

## Getting started

To get started with Android/Lineage OS, you'll need to get familiar with [Repo](https://source.android.com/source/using-repo.html) , [Version Control with Git](https://source.android.com/source/version-control.html) and [Android-Generic Project documentation](https://android-generic-project.gitbook.io/documentation/android-generic-project-getting-started)

### Initializing

To initialize your local repository using the Lineage OS trees, use a command like this:

```
repo init -u https://github.com/LineageOS/android.git -b lineage-18.1 --git-lfs
```

Then we grab the Android-Generic and Waydroid bits:

```
wget -O - https://raw.githubusercontent.com/waydroid/android_vendor_waydroid/lineage-18.1/manifest_scripts/generate-manifest.sh | bash
```

```
git clone https://github.com/android-generic/vendor_ag vendor/ag
```

### Syncing

Then we can sync up:

```
repo sync
```

And setup the local build environment:

```
. build/envsetup.sh
```

### Configuring

#### Legacy Method:

The legacy method is driven by a simple bash script found in vendor/ag/legacy-scripts/waydroid-build/waydroid\_build.sh

```
bash vendor/ag/legacy-scripts/waydroid-build/waydroid_build.sh --help
Compiles and packages Waydroid for target arch

Syntax: 
	waydroid_build [-a|--arch arm|arm64|x86|x86_64] [-c|--clean] [-p|--package] [-r|--rom_name Name]
options:
	-a|--arch (option) Specify arch for build (arm, arm64, x86, x86_64)
	-c|clean     Run 'make clean' before build
	-p|--package     Package build using ROM_NAME
	-r|--rom_name (ROM_NAME) Name used for package build filename (ex: Lineage-17.1)
```

So to compile Waydroid for x86\_64, making clean, and package it in a .zip. You would use this command:

```
bash vendor/ag/legacy-scripts/waydroid-build/waydroid_build.sh -a x86_64 -c -p
```

#### GUI Method:

We now want to use AG for the following portions. So in the terminal, type:

```
ag-menu waydroid
```

You should now see a menu like this:

![](/files/OB1bQBavrNkKKlf7oQZ6)

We can skip the first 2 steps (01-generate-manifest-gui & 02-sync-project), and continue to the

#### 03-apply-base-patches

Click on it and hit OK.

This will start to apply all the waydroid patches on top of Lineage OS. If there are any conflicts, please refer to the [Manual Patch Resolution](/development/manual-patch-resolution) doc. Otherwise, you can continue to the next step.

#### 10-build-options

The build options are mostly the same as native PC builds, so we can explore them a little.

#### Select Product Type:

![](/files/Twb85ZpqcQXIKvr2nGQY)

This will let you select the target device for compiling

#### Select Variant Type:

![](/files/T5u3ZnejiuBhzFJUNP5A)

This will allow you to select the variant type (user, userdebug, eng). Userdebug is the most common for testing.

Select Apps Type:

![](/files/Ohz7Am1pzqQOzWHv6vOC)

<mark style="color:orange;">!!WARNING - NOT ALL ARCH TARGETS ARE FULLY SUPPORTED YET!!</mark>\
This will let you compile Waydroid with various app types included (FOSS, GMS, EMU-Gapps, OpenGapps & Vanilla)

#### Select Desktop Mode Integration:

![](/files/FpqMvHooewWylFiWFUOu)

Waydroid by default includes one type of custom Desktop Mode UI, and that is Boringdroid. This will let you select an alternative option to package along side.

Select Extra Options:

![](/files/YVyUpRdwZcgJTWdekUse)

Make Clean before build - Self explanatory, it runs 'make clean' before compiling

Generate Package .zip - Generated a package .zip after compile if complete <mark style="color:orange;">(requires 7zz & simg2img to be installed)</mark>

#### Run Make Clean:

Just runs 'make clean', nothing fancy

#### Start the Build:

This will launch the compile with all the selected portions from above. If it requires any missing information, the terminal or popup window will let you know.

From here, things are pretty much 1:1 for AG's PC build instructions, so you can refer to the [Android-Generic Project Documentation](https://android-generic-project.gitbook.io/documentation/android-generic-project-getting-started) for further instructions


# Getting Essential Information

Useful information belongs in two places the methods of getting this information are as follows. If someone asks for the logs, it is best to give them the full output of these commands as well as include them on any issue tickets you create:

`sudo systemctl status waydroid-container.service`

`waydroid log`

`sudo waydroid logcat > ~/waydroid-logcat.txt`

It is also important to make sure your kernel supports binder and either ashmem or memfd, you can verify support in your kernel by using one of the following commands.

`grep -i -e android -e memfd -e ashmem "/boot/config-$(uname -r)"`

Or on some distros:

`zgrep -i -e android -e memfd -e ashmem /proc/config.gz`

If you do not have support, you may need to change to a supported kernel or look at patched anbox-modules.dkms.

Another important piece of information is knowing what linux enviroment you are using. These two commands contain the relevant information:

`lsb_release -a` and `uname -a`


# Networking Issues

### Getting network info

Run the command below to get the information of various network interfaces.

`ip addr show`

### Setting up your firewall

* **firewalld**

```bash
firewall-cmd --zone=trusted --add-interface=waydroid0 --permanent
```

* **UFW** or **GUFW**

```bash
sudo ufw allow 53
sudo ufw allow 67
sudo ufw default allow FORWARD
```

* **IPTABLES** Check if your IPTABLES it's set the FORWARD policy with DROP

```bash
iptables --list-rules | grep FORWARD 
```

If yes, set ACCEPT

```bash
iptables -P FORWARD ACCEPT
```


# Known Issues

### Container fails to start: dnsmasq cannot open pid file

#### One cause for this issues is apparmor, the fix is as follows

Edit `/etc/apparmor.d/usr.sbin.dnsmasq` OR `/etc/apparmor.d/local/usr.sbin.dnsmasq`

adding the below to it.

```
@{run}/waydroid-lxc/ r,
@{run}/waydroid-lxc/* rw,
```

### Graphical issues.

Dual GPUs are known to cause an issue where the display is garbled or flickering. You can try [this script](https://github.com/Quackdoc/waydroid-scripts/blob/main/waydroid-choose-gpu.sh) to choose which GPU should be used by Waydroid

### Container fails to start after upgrade to Android 13 (LineageOS 20)

From Android 13 onwards, the filesystem on your home directory needs to support ACLs. If you use BTRFS, for instance with an encrypted `systemd-homed` directory, check that it isn't mounted with the `noacl` mount option.

If you are using `systemd-homed`, create the file `/etc/systemd/system/systemd-homed.service.d/btrfs-acl.conf` containing the following.

```
[Service]
Environment=SYSTEMD_HOME_MOUNT_OPTIONS_BTRFS=acl,compress=zstd:1,user_subvol_rm_allowed
```


# General Troubleshooting

If you run into issues, take a look at the official Issue Tracker \[Waydroid issue tracker]\(https\://github.com/waydroid/waydroid/issues)

#### General tips

Waydroid is in rapid developement so if you face issues, here is a good list of steps to do first:

1. Make sure your Waydroid package is up to date;
2. Make sure you have the latest Waydroid image by running # waydroid upgrade;
3. Reset Waydroid:
   * stop the `waydroid-container.service` `# systemctl stop waydroid-container.service`
   * cleanup `sudo rm -rf /var/lib/waydroid /home/.waydroid ~/waydroid ~/.share/waydroid ~/.local/share/applications/*aydroid* ~/.local/share/waydroid`
   * initialise `# waydroid init -f` or `# waydroid init -f -i /usr/share/waydroid-extra/images`
   * start the service again `# systemctl start waydroid-container.service`

#### Failed to start Clipboard manager service

Install [pyclip](https://repology.org/project/python:pyclip/versions)

#### Sometimes the physical keyboard does not work

Press Left Alt key.

#### Commands inside Waydroid shell outputs inaccessible or not found

On Arch based distributions there's a "bug" that may appear while working with lxc-attach that may cause this issue with commands inside waydroid shell like adbd or settings. A possible workaround for this would be replace the `# waydroid shell` command with `# lxc-attach -P /var/lib/waydroid/lxc/ -n waydroid --clear-env`.

#### WARNING: Service manager /dev/binder has died

See <https://github.com/waydroid/waydroid/issues/136> You should enable [PSI](https://www.kernel.org/doc/html/latest/accounting/psi.html). Add `psi=1` to kernel command line.