This guide provides instructions on how to set up and launch the
Fuchsia emulator (FEMU) on your machine.

The steps are:

1. [Prerequisites](https://fuchsia.dev/fuchsia-src/get-started/set_up_femu#prerequisites).
2. [Build Fuchsia for FEMU](https://fuchsia.dev/fuchsia-src/get-started/set_up_femu#build-fuchsia-for-femu).
3. [Enable VM acceleration (Optional)](https://fuchsia.dev/fuchsia-src/get-started/set_up_femu#enable-vm-acceleration).
4. [Start FEMU](https://fuchsia.dev/fuchsia-src/get-started/set_up_femu#start-femu).
5. [Discover FEMU](https://fuchsia.dev/fuchsia-src/get-started/set_up_femu#discover-femu).

## 1. Prerequisites

Running FEMU requires that you've completed the following guides:

- [Download the Fuchsia source code](https://fuchsia.dev/docs/get-started/get_fuchsia_source)
- [Configure and build Fuchsia](https://fuchsia.dev/docs/get-started/build_fuchsia)

## 2. Build Fuchsia for FEMU

To run FEMU, you first need to build a Fuchsia system image that supports
the emulator environment. This guide uses `x64` for the board and
`workbench_eng` for the product as an example. (For more information on
supported boards and products, see the [Fuchsia emulator](https://fuchsia.dev/docs/development/build/emulator)
page.)

> [!IMPORTANT]
> **Important:** The generic `arm64` board configuration is intended for physical target hardware and does not support running in the emulator. If you are building for an ARM64 emulator, you must use the `qemu-arm64` board configuration (for example, `terminal.qemu-arm64`).

To build a FEMU Fuchsia image, do the following:

1. Set the Fuchsia build configuration:

       fx set workbench_eng.x64 --release

2. Build Fuchsia:

       fx build

## 3. Enable VM acceleration (Optional)

(**Linux only**) Most Linux machines support VM acceleration through
KVM, which greatly improves the performance and usability of the emulator.

1. If KVM is available on your machine, add yourself to the `kvm` group
   on your machine:

       sudo usermod -a -G kvm ${USER}

2. Log out of all desktop sessions to your machine and then log in again.

3. 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.

## 4. Start FEMU

### Start the package server

Prior to starting the emulator, start the package server.

To start the package server, run the following command:

    fx serve

Once this command is run, it does not terminate and keeps the
Fuchsia package server running on the host machine (unless the
terminal is closed or `Ctrl+C` is pressed on the terminal,
which kills the command).

Alternatively you can background the `fx serve` process.

### Start the emulator

Start the Fuchsia emulator on your Linux machine.

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.

However, even if you're not behind a firewall, there's still some
configuration needed to enable tun/tap networking. The example
upscript at `//scripts/start-unsecure-internet.sh` should work for
the majority of non-corporate users.

To start the emulator, do the following:

1. Start a new terminal.

2. To configure the upscript, run the following command:

       ffx config set emu.upscript FUCHSIA_ROOT/scripts/start-unsecure-internet.sh

   - `start-unsecure-internet.sh` is an example upscript.
   - `FUCHSIA_ROOT` is the path to your Fuchsia directory.
3. Start the emulator with access to external networks:

       ffx emu start --net tap

   `--net` specifies the networking mode for the emulator.
   `--net tap` attaches to a Tun/Tap interface.

   Or, you can start the emulator without access to external networks:

       ffx emu start --net none

   Starting the emulator opens a new window with the title
   **Fuchsia Emulator**.

## 5. Discover FEMU

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>    workbench_eng.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 be not
  discoverable by `ffx target list`.

- `--net tap` and `--net user` allow the device to be discoverable
  when running `ffx target list`.

## Next steps

To learn more about Fuchsia device commands and Fuchsia workflows, see
[Explore Fuchsia](https://fuchsia.dev/docs/get-started/explore_fuchsia).

## Appendix

This section provides additional FEMU options.

### Add target manually

If no target is found after running `ffx target list`, you may add the
target manually by running the following `ffx` command:

    ffx target add device-ip:device-port

### See all available flags

To see a [full list](https://fuchsia.dev/reference/tools/sdk/ffx#emu) of the emulator's supported flags,
run the following command:

    ffx emu start --help

### Run FEMU without GUI support

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

    ffx emu start --headless

### Reboot FEMU

To reboot FEMU, run the following `ffx` command:

    ffx target reboot

### Stop FEMU

To stop FEMU, run the following `ffx` command:

    ffx emu stop

### Configure emulator networking

This section provides instructions on how to configure an IPv6 network
for FEMU on Linux machine using [TUN/TAP](https://en.wikipedia.org/wiki/TUN/TAP).

> [!NOTE]
> **Note:** You only need to do this once per machine.

To enable networking in FEMU using
[tap networking](https://wiki.qemu.org/Documentation/Networking#Tap), do the following:

1. Set up `tuntap`:

       sudo ip tuntap add dev qemu mode tap user $USER

2. Enable the network for `qemu`:

       sudo ip link set qemu up

### Specify GPU mode for FEMU (Experimental)

By default, the FEMU launcher uses [SwiftShader](https://swiftshader.googlesource.com/SwiftShader/)
Vulkan ICD for host graphics rendering. With the `--gpu` flag, you can set the
emulator to use the host GPU hardware for rendering. See the following options:

| GPU emulation method | Description | Flag |
|---|---|---|
| SwiftShader | Use SwiftShader libraries to simulate GPU processing. This is the default mode. | `ffx emu start --gpu swiftshader_indirect` |
| Hardware (host GPU) | Use the host machine's GPU directly to perform GPU processing. | `ffx emu start --gpu host` |
| Auto | Resolve to `host` if there is a hardware GPU available or `swiftshader_indirect` if there isn't a hardware GPU available. | `ffx emu start --gpu auto` |

The `host` and `auto` GPU emulation modes are for **experimental use only** and
are not officially supported at the moment. You may see graphics artifacts, testing
failures or emulator crashes when using these two modes.

### Input interaction profiles (mouse versus touchscreen)

Fuchsia virtual device profiles configure different input interaction modes
depending on the target hardware product characteristics:

- **Mouse Mode (`mouse`)**: Standard desktop mouse emulation pointer layout.
- **Touchscreen Mode (`touch`)**: Emulates interactive touchscreen input.

**Engine compatibility**:
The choice of the emulator background virtualization engine restricts the
input options:

- **FEMU (`--engine femu`)** : Fully supports both `mouse` and `touch` input profiles. This is the default and is required for testing smart displays or touchscreen devices.
- **QEMU (`--engine qemu`)** : Only supports `mouse` pointer emulation inputs. If the selected product bundle defaults to a touchscreen virtual device profile layout, launching it under `--engine qemu` triggers capability warnings or execution errors.

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/get-started/set_up_femu.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/get-started/set_up_femu.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/get-started/set_up_femu.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/get-started/set_up_femu.md "Edit the source code of this page")