Run the Android Emulator on a Linux server (headless)

The Android Emulator from Google's Android SDK runs on Linux with KVM acceleration and can run headless, without a window. That makes a Linux server a good host for app tests, automation and always-on Android workloads. This guide sets it up from the command line and shows how to control and view it.

Before you start

• A Linux server with KVM: an Android GPU server on Linux, a VDS or a nested dedicated server, running Ubuntu 24.04 or Debian 13. Check KVM as in VDS and nested virtualization: kvm-ok must report that KVM acceleration can be used.
• A non-root user with sudo and enough disk space for the SDK and system images (several gigabytes).

Step 1: Install Java and give your user KVM access

The SDK tools run on Java:

sudo apt update
sudo apt install openjdk-21-jre-headless unzip
ls -l /dev/kvm
sudo usermod -aG kvm $USER

Log out and in again so the kvm group applies.

Step 2: Install the command-line tools

On Android's download page, copy the link of the Command line tools only package for Linux, then unpack it into the folder layout sdkmanager expects:

mkdir -p ~/android-sdk/cmdline-tools
cd ~/android-sdk/cmdline-tools
wget -O cmdline-tools.zip "PASTE-THE-DOWNLOAD-LINK-HERE"
unzip cmdline-tools.zip
mv cmdline-tools latest

Add the tools to your shell:

cat >> ~/.bashrc <<'EOF'
export ANDROID_HOME=$HOME/android-sdk
export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH
EOF
source ~/.bashrc

Verify: sdkmanager --version prints a version number.

Step 3: Install the emulator and a system image

Accept the licences, list the available system images and install the platform tools, the emulator and one image:

sdkmanager --licenses
sdkmanager --list | grep "system-images" | grep x86_64
sdkmanager "platform-tools" "emulator" "system-images;android-36;google_apis;x86_64"

Use an image name exactly as --list printed it. Verify: emulator -accel-check reports that KVM is installed and usable.

Step 4: Create a virtual device

avdmanager create avd -n test -k "system-images;android-36;google_apis;x86_64"
emulator -list-avds

Answer no when asked for a custom hardware profile, unless you need one.

Step 5: Start it headless and control it with adb

Start the emulator without a window, audio or boot animation, using software rendering for the screen:

emulator -avd test -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect &
adb wait-for-device
adb shell getprop sys.boot_completed

When the last command prints 1, Android has booted. Install and start apps with adb:

adb install app.apk
adb devices

Run long sessions inside tmux, so the emulator keeps running when your SSH connection ends. Stop it with adb emu kill.

Step 6: View the screen from your computer

Install scrcpy on your computer, then forward the server's adb server through SSH, as the scrcpy documentation describes:

ssh -CN -L5038:localhost:5037 -L27183:localhost:27183 you@203.0.113.10

In a second terminal on your computer:

export ADB_SERVER_SOCKET=tcp:localhost:5038
scrcpy --force-adb-forward

A window with the emulator's screen opens; you can use mouse and keyboard in it. Keep the SSH tunnel open while you work.

Troubleshooting

emulator -accel-check reports that KVM is not usable. Check ls -l /dev/kvm, your kvm group membership and the server type; see nested virtualization problems.

sdkmanager stops with a Java error. Install a current OpenJDK runtime and run it again.

adb devices shows the emulator as offline. Android is still booting. Wait for sys.boot_completed to print 1.

The emulator is slow. Give the virtual device more CPU cores and memory with avdmanager's hardware options or by editing its config.ini, and keep other load low.

More: Android emulator troubleshooting.

Next steps

• Windows emulators instead: Android emulator servers: getting started.
• Several devices at once: run many emulator instances.