Skip to content

Add documentation for Windows ARM device limitations with Android emulators #3038

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add documentation for Windows ARM device limitations with Android emulators #3038

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cf80948
Initial plan
Copilot Sep 19, 2025
200e399
Add Windows ARM device limitations documentation for Android emulators
Copilot Sep 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/android/emulator/hardware-acceleration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,22 @@ For the best experience on Windows, it's recommended you use WHPX to accelerate
> [!IMPORTANT]
> A Virtual Machine (VM) accelerated emulator can run inside another VM, including Microsoft Dev Box, provided that nested virtualization is enabled in the VM.

### Windows ARM device limitations

The Android emulator currently requires x64 processor architecture and is **not supported on Windows ARM devices**. This limitation affects devices such as:

- Surface Pro X
- Surface Pro 9 (5G/ARM variant)
- Other Windows devices with ARM64 processors (Snapdragon, etc.)

If you're using a Windows ARM device, consider the following alternatives:

- Use a physical Android device for testing via USB debugging. For more information, see [Set up Android device for debugging](~/android/device/setup.md).
- Use cloud-based testing services or remote development environments with x64 architecture.
- Consider using Windows Subsystem for Android (WSA) if available, though this has different limitations and capabilities compared to the Android emulator.

For the latest information about Android emulator requirements, see [Android Emulator requirements](https://developer.android.com/studio/run/emulator#requirements) on developer.android.com.

For information about launching and debugging with the Android emulator, see [Debugging on the Android Emulator](debug-on-emulator.md).

## Accelerate with Hyper-V
Expand Down
17 changes: 17 additions & 0 deletions docs/android/emulator/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ Performance issues are typically caused by one of the following problems:

- The emulator is running without hardware acceleration.
- The virtual device running in the emulator using an Arm-based image.
- You're trying to run the emulator on a Windows ARM device (not supported).

The following sections cover these scenarios in more detail.

Expand All @@ -71,6 +72,22 @@ When you start a virtual device, and you don't have hardware acceleration enable

To fix this error, follow the troubleshooting steps in the [Hardware acceleration issues](#hardware-acceleration-issues) section.

### Windows ARM device compatibility

The Android emulator is **not supported on Windows ARM devices** and will not run on devices with ARM64 processors such as:

- Surface Pro X
- Surface Pro 9 (5G/ARM variant)
- Other Windows devices with Snapdragon or ARM-based processors

If you're using a Windows ARM device and encounter emulator startup issues or performance problems, this is likely due to the architecture incompatibility. The Android emulator requires x64 processor architecture.

**Alternatives for Windows ARM devices:**

- Use a physical Android device connected via USB for debugging. For setup instructions, see [Set up Android device for debugging](~/android/device/setup.md).
- Use cloud-based development environments or remote machines with x64 architecture.
- Consider Windows Subsystem for Android (WSA) if available in your region, though it has different capabilities and limitations.

## Hardware acceleration issues

When using hardware acceleration, you may run into configuration problems or conflicts with other software on your computer. The first step in troubleshooting is verifying that hardware acceleration is enabled. You can use the Android's SDK to check this setting. Open a command prompt and entering the following command:
Expand Down
3 changes: 3 additions & 0 deletions docs/get-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,6 +295,9 @@ To download and install an Android emulator on which to run your apps:

For more information about the `avdmanager` command, see [avdmanager](https://developer.android.com/tools/avdmanager) on developer.android.com.

> [!IMPORTANT]
> **Windows ARM devices**: The Android emulator requires x64 architecture and is not supported on Windows ARM devices (such as Surface Pro X). If you're using a Windows ARM device, consider using a physical Android device for testing instead. For more information, see [Set up Android device for debugging](~/android/device/setup.md).

### iOS and macOS

To set up your Mac for .NET MAUI development on iOS and Mac Catalyst with Visual Studio Code:
Expand Down