This guide provides instructions on how to set up and launch the Fuchsia emulator (FEMU) on your machine.
The steps are:
Running FEMU requires that you've completed the following guides:
To run FEMU, you first need to build a Fuchsia system image that supports the emulator environment. This guide uses qemu-x64 for the board and workstation for the product as an example.
To build a FEMU Fuchsia image, do the following:
Set the Fuchsia build configuration:
fx set workstation.qemu-x64 --release
Build Fuchsia:
fx build
For more information on supported boards and products, see the Fuchsia emulator (FEMU) overview page.
(Linux only) Most Linux machines support VM acceleration through KVM, which greatly improves the performance and usability of the emulator.
If KVM is available on your machine, update your group permission to enable KVM.
{Linux}
To enable KVM on your machine, do the following:
Note: You only need to do this once per machine.
Add yourself to the kvm group on your machine:
sudo usermod -a -G kvm ${USER}
Log out of all desktop sessions to your machine and then log in again.
To verify that KVM is configured correctly, run the following command:
if [[ -r /dev/kvm ]] && grep '^flags' /proc/cpuinfo | grep -qE 'vmx|svm'; then echo 'KVM is working'; else echo 'KVM not working'; fi
Verify that this command prints the following line:
KVM is working
If you see KVM not working, you may need to reboot your machine for the permission change to take effect.
{macOS}
No additional setup is required for macOS.
Instead of KVM, the Fuchsia emulator on macOS uses the Hypervisor framework{: .external}.
Prior to starting the emulator, start the package server.
To start the the package server, run the following command:
fx serve
Note: Alternatively you can background the fx serve process.
To start the emulator on your Linux machine, do the following:
{Linux}
Configure the upscript by running the following command:
Note: If your machine is behind a firewall, you may need to apply some additional configuration to allow the emulator to access the network. This is typically accomplished by running an “upscript”, which sets up the interfaces and firewall access rules for the current process. If you‘re on a corporate network, check with your internal networking team to see if they have an existing upscript for you to use. If you’re not behind a firewall, there's still some configuration needed to enable tun/tap networking. The example upscript at {{ ‘’ }}FUCHSIA_ROOT{{ ‘’ }}/scripts/start-unsecure-internet.sh should work for the majority of non-corporate users.
ffx config set emu.upscript {{ '<var>' }}FUCHSIA_ROOT{{ '</var>' }}/scripts/start-unsecure-internet.sh
start-unsecure-internet.sh is an example upscript.FUCHSIA_ROOT is the path to your Fuchsia directory.Start FEMU
To start the emulator with access to external networks, run the following command:
ffx emu start --net tap
--net specifies the networking mode for the emulator. --net tap attaches to a Tun/Tap interface.To start the emulator without access to external networks, run the following command:
ffx emu start --net none
Starting the emulator opens a new window with the title Fuchsia Emulator. When the emulator is finished booting, you are returned to the command prompt, and the emulator runs in the background.
{macOS}
To start FEMU on macOS, do the following:
Start FEMU:
ffx emu start
If you launch FEMU for the first time on your macOS (including after a reboot), a window pops up asking if you want to allow the process aemu to run on your machine. Click Allow.
This command opens a new window with the title Fuchsia Emulator. When the emulator is finished booting, you are returned to the command prompt, and the emulator runs in the background.
(Optional) If you need to specify the launched Fuchsia emulator, you can run the fx set-device command in the same terminal:
fx set-device {{ '<var>' }}NAME{{ '</var>' }}
Replace the following:
NAME: Use the desired value from the ffx emu list or ffx target list command's output. fuchsia-emulator is the default value.To discover the Fuchsia emulator as a running Fuchsia device, run the following command:
ffx target list
This command prints output similar to the following:
$ ffx target list NAME SERIAL TYPE STATE ADDRS/IP RCS fuchsia-emulator <unknown> workstation.qemu-x64 Product [fe80::866a:a5ea:cd9e:69f6%qemu] N
fuchsia-emulator is the default node name of the Fuchsia emulator.
The output of ffx target list is influenced by the --net option in the following ways:
--net none disables networking, which causes the device to not be discoverable when running ffx target list.--net tap and --net user allow the device to be discoverable when running ffx target list.To learn more about Fuchsia device commands and Fuchsia workflows, see Explore Fuchsia.
This section provides additional FEMU options.
To see a full list of the emulator's supported flags:
ffx emu start --help
If you don't need graphics or working under the remote workflow, you can run FEMU in headless mode:
ffx emu start --headless
By default, the FEMU launcher uses software rendering using SwiftShader{: .external}. To force FEMU to use a specific graphics emulation method, use the parameters --gpu host or --gpu guest with the ffx emu start command.
These are the valid commands and options:
To reboot FEMU, run the following ffx command:
ffx target reboot
To stop FEMU, run the following ffx command:
ffx emu stop
This section provides instructions on how to configure an IPv6 network for FEMU on Linux machine using TUN/TAP{: .external}.
{Linux}
Note: This has to be completed once per machine.
To enable networking in FEMU using tap networking{: .external}, do the following:
Set up tuntap:
sudo ip tuntap add dev qemu mode tap user $USER
Enable the network for qemu:
sudo ip link set qemu up
{macOS}
No additional IPv6 network setup is required for macOS.
User Networking (SLIRP){: .external} is the default network setup for FEMU on macOS – while this setup does not support Fuchsia device discovery, you can still use fx tools (for example,fx ssh) to interact with your FEMU instance.