The Fuchsia emulator (FEMU) is the default emulator for Fuchsia. FEMU allows you to test Fuchsia components and applications without a physical Fuchsia device. FEMU is included in the Fuchsia source tree. FEMU is downloaded (or updated) by `jiri`, as part of `jiri update` or `jiri run-hooks`, and is fetched into the `/prebuilt/third_party/aemu` directory of your Fuchsia source tree. You can launch FEMU using `ffx emu`. ## FEMU, AEMU, and QEMU FEMU is based on the [Android Emulator (AEMU)](https://developer.android.com/studio/run/emulator), which is a fork of [QEMU](https://www.qemu.org/) -- in some instances, such as [debugging the Zircon kernel](https://fuchsia.dev/fuchsia-src/development/build/emulator#debugging-zircon-kernel), you should use QEMU instead. Due to legacy issues, there may be references to AEMU in the code and documentation. ### Debugging Zircon Kernel If you want to debug the Zircon kernel, you should use `fx qemu` instead. Read [Debugging the Kernel using QEMU](https://fuchsia.dev/docs/development/debugging/qemu) to learn more. This is for kernel developers. Most Fuchsia developers do not need to use this workflow. ## Features FEMU looks and behaves like a Fuchsia device, except that no paving or flashing is required with FEMU. The features of FEMU include: - **GUI Support:** You can run Fuchsia with the GUI (by default) or without the GUI (using the `--headless` argument). - **GPU Support:** You can run with the host's GPU (by default) with full [Vulkan](https://fuchsia.dev/docs/development/graphics/magma/concepts/vulkan) support, or you can choose software rendering using [SwiftShader](https://swiftshader.googlesource.com/SwiftShader/). - **Remote Development:** You can use a remote desktop with FEMU over Chrome Remote Desktop. - **UEFI/GPT Support** : You can approximate a physical device including GPT partition layout based on Fuchsia's ABR-scheme (using the `--uefi` argument). To see full list of supported flags: ffx emu start --help ## Image and board support When setting up FEMU using `fx set`, FEMU supports the following boards: - `x64` - `qemu-arm64` > [!IMPORTANT] > **Important:** The generic `arm64` board configuration does not support running in the emulator because it is configured for physical target hardware. To run Fuchsia in the emulator for ARM64, you must use the `qemu-arm64` board configuration (for example, `terminal.qemu-arm64`). With the Fuchsia SDK, FEMU supports pre-built images, including: - `core.x64` - `workbench_eng.x64` - `terminal.qemu-arm64` ARM64 support (`qemu-arm64`) is very limited and not recommended. Use `ffx --machine product list --version ` to see the full list of products available from the SDK and the corresponding transfer manifests, and `ffx product download ` to download those products. ## Networking The `--net` flag specifies the networking mode for the emulator. `--net` requires a value to indicate which kind of networking to implement. `--net` has the following possible values: - `tap`: Attaches a Tun/Tap interface. - `user`: Sets up mapped ports through SLiRP. - `none`: Disables networking. - `auto`: Checks the host system's capabilities and selects `tap` if it is available or `user` if a Tap interface is unavailable. `auto` is the default. On Linux, FEMU should generally be run with the `--net tap` flag that provides networking through an emulated NIC. > [!NOTE] > **Note:** Instructions for setting up networking for FEMU is in the [Start the Fuchsia Emulator](https://fuchsia.dev/docs/get-started/set_up_femu) guide. `--net tap` and `--net user` allow the emulator to be discoverable when running `ffx target list`. `--net none` disables networking, which causes the emulator to not be discoverable after running `ffx target list`. If starting the emulator with `ffx emu start --net user`, an available TCP port from the host is picked and forwarded to the emulator's SSH port. You can manually set the SSH address and use `fx` tools to interact with your emulator by running the following command: ffx emu start --net user --port-map PORT-NAME:PORT-NUMBER Replace the following: - PORT-NAME: The chosen name for the port. An example port name could be `ssh`. - PORT-NUMBER: The number of the port. An example port number is `8022`. Any named ports can be set the same way. The ports that can be mapped are named in the virtual device specification. To verify that your `fx` tool is using the correct port, run the following command: ffx target list The device's SSH address is listed under `ADDRS/IP`. If a port is not specified as part of the address, the default SSH port (22) is used. To SSH into the emulator, run the following command: fx shell ## Unsupported CPUs FEMU currently does not run on: - ARM64 processors, including the Apple M1 processor. - AMD processors. ## Supported hardware for graphics acceleration FEMU currently supports Nvidia Quadro on Linux for hardware graphics acceleration ([Nvidia Linux Drivers](https://www.nvidia.com/drivers)). FEMU uses a software renderer fallback for unsupported GPUs. ## Common usage To launch FEMU, complete the [Get started with Fuchsia](https://fuchsia.dev/docs/get-started/README) guide. Alternatively, you can use the Fuchsia SDK and use pre-built system images. Once you're able to launch FEMU, you can perform the following task: - [Test components](https://fuchsia.dev/docs/development/run/run-test-component) [](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/build/emulator.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/build/emulator.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/build/emulator.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/build/emulator.md "Edit the source code of this page")