Google is committed to advancing racial equity for Black communities. See how.

Set up and start the Fuchsia emulator (FEMU)

This document describes how to set up and run the Fuchsia emulator (FEMU), including networking and GPU support setup.

Prerequisites

To run FEMU, you must have

Building Fuchsia for FEMU

Before you can use FEMU, you need to build Fuchsia using fx set, specifying a qemu board and supported product. This example uses qemu-x64 for the board and workstation for the product:

fx set workstation.qemu-x64 --release [--with=...]
fx build

Configure network

For Fuchsia's ephemeral software to work with FEMU, you need to configure an IPv6 network.

Linux

To enable networking in FEMU, run the following commands:

sudo ip tuntap add dev qemu mode tap user $USER
sudo ip link set qemu up

macOS

Networking for FEMU is set up by default for macOS.

Start FEMU

The most common way to run FEMU is with networking enabled, using the following commands.

Linux

fx emu -N

Once you run the command, a separate window opens with the title "Fuchsia Emulator". You can run shell commands in this window, just like you would on a Fuchsia device.

macOS

fx vdl start --host-gpu

To enable fx tools (like fx ssh) on macOS, run the following command:

fx set-device 127.0.0.1:${SSH_PORT} // where ${SSH_PORT} is a line printed in stdout

Additional FEMU options

Input options

By default FEMU uses a mouse pointer for input. You can add the argument --pointing-device touch for touch input instead.

Linux

fx emu --pointing-device touch

macOS

fx vdl start --pointing-device touch

Run FEMU without GUI support

If you don't need graphics or working under the remote workflow, you can run FEMU in headless mode:

Linux

fx emu --headless

macOS

fx vdl start --headless

Specify GPU used by FEMU

By default, FEMU tries using the host GPU automatically if it is available, and falls back to software rendering using SwiftShader if a host GPU is unavailable.

You can also add the argument --host-gpu or --software-gpu to the fx emu command to force FEMU to use a specific graphics device. The commands and flags are listed below:

Linux

GPU Emulation method Explanation fx emu flag
hardware (host GPU) Uses the host machine’s GPU directly to perform GPU processing. fx emu --host-gpu
software (host CPU) Uses the host machine’s CPU to simulate GPU processing. fx emu --software-gpu

macOS

GPU Emulation method Explanation fx vdl flag
hardware (host GPU) Uses the host machine’s GPU directly to perform GPU processing. fx vdl start --host-gpu
software (host CPU) Uses the host machine’s CPU to simulate GPU processing. fx vdl start --software-gpu

Supported hardware for graphics acceleration

FEMU currently supports a limited set of GPUs on macOS and Linux for hardware graphics acceleration. FEMU uses a software renderer fallback for unsupported GPUs.

Operating System GPU Manufacturer OS / Driver Version
Linux Nvidia Quadro Nvidia Linux Drivers 440.100+
macOS Intel HD Graphics macOS version 10.15+
macOS AMD Radeon Pro macOS version 10.15+

Exit FEMU

To exit FEMU, run dm poweroff in the FEMU terminal.

Next steps