You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: landing/arm-docs/apps-on-arm-program-compat-troubleshooter.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Program Compatibility Troubleshooter on Arm
3
3
description: Guidance for adjusting compatibility settings if your app isn't working correctly on Arm
4
-
ms.date: 02/23/2024
4
+
ms.date: 11/06/2025
5
5
ms.topic: troubleshooting-general
6
6
ms.service: windows
7
7
ms.subservice: arm
@@ -10,7 +10,7 @@ ms.reviewer: marcs
10
10
11
11
# Program Compatibility Troubleshooter on Arm
12
12
13
-
PCs powered by Arm provide great application compatibility and allow you to run your existing unmodified x86 win32 applications. Arm apps run natively without any emulation, while x86 and x64 apps run under emulation on Arm devices.
13
+
PCs powered by Arm provide great application compatibility and allow you to run your existing unmodified x86 Win32 applications. Arm apps run natively without any emulation, while x86 and x64 apps run under emulation on Arm devices.
14
14
15
15
However, sometimes the emulation performs optimizations that don't result in the best user experience. You can use the **Program Compatibility Troubleshooter** to toggle emulation settings for your x86 or x64 app, reducing the default optimizations and potentially increasing compatibility.
16
16
@@ -38,7 +38,7 @@ All options enable the settings that are applicable and applied on Windows Deskt
38
38
39
39
You can toggle emulation settings by right-clicking the executable and selecting **Properties**.
40
40
41
-
On ARM, a section titled **Windows 10 on ARM** or **Windows 11 on ARM** will be available in the **Compatibility** tab. Select **Change emulation settings** to launch an Emulations Properties window.
41
+
On Arm, a section titled **Windows 10 on Arm** or **Windows 11 on Arm** will be available in the **Compatibility** tab. Select **Change emulation settings** to launch an Emulations Properties window.
description: Common issues with Arm32 apps when running on Arm, and how to fix them.
4
-
ms.date: 06/25/2021
4
+
ms.date: 11/06/2025
5
5
ms.topic: troubleshooting-general
6
6
ms.service: windows
7
7
ms.subservice: arm
@@ -10,7 +10,7 @@ ms.reviewer: marcs
10
10
11
11
# Troubleshooting Arm UWP apps
12
12
13
-
If your Arm32 or Arm64 UWP app isn't working correctly on Arm, here's some guidance that may help.
13
+
If your Arm32 or Arm64 UWP app isn't working correctly on Arm, here's some guidance that might help.
14
14
15
15
>[!NOTE]
16
16
> To build your UWP application to natively target the Arm64 platform, you must have Visual Studio 2017 version 15.9 or later, or Visual Studio 2019. For more information, see [this blog post](https://blogs.windows.com/buildingapps/2018/11/15/official-support-for-windows-10-on-arm-development).
@@ -21,26 +21,26 @@ Here are some common issues to keep in mind when troubleshooting Arm32 and Arm64
21
21
22
22
### Using Windows 10 Mobile-only APIs on Arm-based processors
23
23
24
-
Arm apps may run into problems when using mobile-only APIs (for example, **HardwareButtons**). To mitigate this, you can dynamically detect whether your app is running on Windows 10 Mobile before calling these APIs. For more info, see [Dynamically detecting features with API contracts](/windows/uwp/debug-test-perf/version-adaptive-apps#api-contracts).
24
+
Arm apps might run into problems when using mobile-only APIs (for example, **HardwareButtons**). To mitigate this issue, you can dynamically detect whether your app is running on Windows 10 Mobile before calling these APIs. For more info, see [Dynamically detecting features with API contracts](/windows/uwp/debug-test-perf/version-adaptive-apps#api-contracts).
25
25
26
26
### Including dependencies not supported by UWP apps
27
27
28
-
Universal Windows Platform (UWP) apps that aren't properly built with Visual Studio and the UWP SDK may have dependencies on OS components that aren't available to Arm apps running on an Arm64 system. Examples of these dependencies include:
28
+
Universal Windows Platform (UWP) apps that aren't properly built with Visual Studio and the UWP SDK might have dependencies on OS components that aren't available to Arm apps running on an Arm64 system. Examples of these dependencies include:
29
29
30
30
- Expecting parts of the .NET Framework to be available.
31
31
- Referencing third-party .NET components that aren't compatible with UWP.
32
32
33
-
These issues can be resolved by: removing the unavailable dependencies and rebuilding the app by using the latest Microsoft Visual Studio and UWP SDK versions; or as a last resort, removing the Arm app from the Microsoft Store, so that the x86 version of the app (if available) is downloaded to users' PCs.
33
+
You can resolve these issues by removing the unavailable dependencies and rebuilding the app by using the latest Microsoft Visual Studio and UWP SDK versions. As a last resort, you can remove the Arm app from the Microsoft Store so that the x86 version of the app (if available) is downloaded to users' PCs.
34
34
35
-
For more info on .NET APIs available for UWP apps, see [.NET for UWP apps](/dotnet/api/index?view=dotnet-uwp-10.0&preserve-view=true)
35
+
For more info on .NET APIs available for UWP apps, see [.NET for UWP apps](/dotnet/api/index?view=dotnet-uwp-10.0&preserve-view=true).
36
36
37
37
### Compiling an app with an older version of Visual Studio and SDK
38
38
39
-
If you're running into issues, be sure to use the latest versions of Microsoft Visual Studio and the Windows SDK to compile your app. Apps compiled with an earlier version of Visual Studio and the SDK may have issues that have been fixed in later versions.
39
+
If you run into issues, be sure to use the latest versions of Microsoft Visual Studio and the Windows SDK to compile your app. Apps compiled with an earlier version of Visual Studio and the SDK might have issues that are fixed in later versions.
40
40
41
41
## Debugging
42
42
43
43
You can use existing tools for developing apps for the Arm platform. Here are some helpful resources.
44
44
45
-
- Visual Studio 15.5 Preview 1 and later supports running Arm32 apps by using Universal Authentication mode. This automatically bootstraps the necessary remote debugging tools.
45
+
- Visual Studio 15.5 Preview 1 and later supports running Arm32 apps by using Universal Authentication mode. This mode automatically bootstraps the necessary remote debugging tools.
46
46
- See [Debugging on Arm64](/windows-hardware/drivers/debugger/debugging-arm64) to learn more about tools and strategies for debugging on Arm.
description: Learn how to troubleshoot and fix common issues with an x86 desktop app running on Arm64 including information about drivers, shell extensions, and debugging.
4
-
ms.date: 06/25/2021
4
+
ms.date: 11/06/2025
5
5
ms.topic: troubleshooting-general
6
6
ms.service: windows
7
7
ms.subservice: arm
@@ -11,47 +11,47 @@ ms.reviewer: marcs
11
11
# Troubleshooting x86 desktop apps
12
12
13
13
>[!IMPORTANT]
14
-
> With Visual Studio 2017 or later, it is possible recompile your app to Arm64 or Arm64EC so that your app runs at full native speed. For more info about compiling as Arm64, see the blog post: [Official support for Windows 10 on Arm development](https://blogs.windows.com/buildingapps/2018/11/15/official-support-for-windows-10-on-arm-development). For information about Arm64EC, see [Announcing Arm64EC: Building Native and Interoperable Apps for Windows 11 on Arm](https://aka.ms/arm64ecannounceblog).
14
+
> With Visual Studio 2017 or later, you can recompile your app to Arm64 or Arm64EC so that your app runs at full native speed. For more info about compiling as Arm64, see the blog post: [Official support for Windows 10 on Arm development](https://blogs.windows.com/buildingapps/2018/11/15/official-support-for-windows-10-on-arm-development). For information about Arm64EC, see [Announcing Arm64EC: Building Native and Interoperable Apps for Windows 11 on Arm](https://aka.ms/arm64ecannounceblog).
15
15
16
-
If an x86 desktop app doesn't work the way it does on an x86 machine, here's some guidance to help you troubleshoot.
16
+
If an x86 desktop app doesn't work the way it does on an x86 machine, use the following guidance to help you troubleshoot.
17
17
18
18
|Issue|Solution|
19
19
|-----|--------|
20
20
| Your app relies on a driver that isn't designed for Arm. | Recompile your x86 driver to Arm64. See [Building Arm64 Drivers with the WDK](/windows-hardware/drivers/develop/building-arm64-drivers). |
21
-
| Your app is available only for x64. | If you develop for Microsoft Store, submit an Arm version of your app. For more info, see [App package architectures](/windows/msix/package/device-architecture). If you're a Win32 developer, we recommend you recompile your app to Arm64. For more info see [Early preview of Visual Studio support for Windows 10 on Arm development](https://blogs.windows.com/buildingapps/2018/05/08/visual-studio-support-for-windows-10-on-arm-development/). |
22
-
| Your app uses an OpenGL version later than 1.1 or requires hardware-accelerated OpenGL. | Use the DirectX mode of the app, if it's available. x86 apps that use DirectX 9, DirectX 10, DirectX 11, and DirectX 12 will work on Arm. For more info, see [DirectX Graphics and Gaming](/windows/desktop/directx). |
23
-
| Your x86 app does not work as expected. | Try using the Compatibility Troubleshooter by following guidance from [Program Compatibility Troubleshooter on Arm](apps-on-arm-program-compat-troubleshooter.md). For some other troubleshooting steps, see the [Troubleshooting x86 apps on Arm](apps-on-arm-troubleshooting-x86.md) article. |
21
+
| Your app is available only for x64. | If you develop for Microsoft Store, submit an Arm version of your app. For more info, see [App package architectures](/windows/msix/package/device-architecture). If you're a Win32 developer, recompile your app to Arm64. For more info see [Early preview of Visual Studio support for Windows 10 on Arm development](https://blogs.windows.com/buildingapps/2018/05/08/visual-studio-support-for-windows-10-on-arm-development/). |
22
+
| Your app uses an OpenGL version later than 1.1 or requires hardware-accelerated OpenGL. | Use the DirectX mode of the app, if it's available. x86 apps that use DirectX 9, DirectX 10, DirectX 11, and DirectX 12 work on Arm. For more info, see [DirectX Graphics and Gaming](/windows/desktop/directx). |
23
+
| Your x86 app doesn't work as expected. | Try using the Compatibility Troubleshooter by following guidance from [Program Compatibility Troubleshooter on Arm](apps-on-arm-program-compat-troubleshooter.md). For some other troubleshooting steps, see the [Troubleshooting x86 apps on Arm](apps-on-arm-troubleshooting-x86.md) article. |
24
24
25
25
## Best practices for WOW
26
26
27
-
One common problem occurs when an app discovers that it's running under WOW and then assumes that it is on an x64 system. Having made this assumption, the app may do the following:
27
+
One common problem occurs when an app discovers that it's running under WOW and then assumes that it is on an x64 system. With this assumption, the app might do the following actions:
28
28
29
29
- Try to install the x64 version of itself, which isn't supported on Arm.
30
30
- Check for other software under the native registry view.
31
31
- Assume that a 64-bit .NET framework is available.
32
32
33
-
Generally, an app should not make assumptions about the host system when it is determined to run under WOW. Avoid interacting with native components of the OS as much as possible.
33
+
Generally, an app shouldn't make assumptions about the host system when it is determined to run under WOW. Avoid interacting with native components of the OS as much as possible.
34
34
35
-
An app may place registry keys under the native registry view, or perform functions based on the presence of WOW. The original **IsWow64Process** indicates only whether the app is running on an x64 machine. Apps should now use [IsWow64Process2](/windows/desktop/api/wow64apiset/nf-wow64apiset-iswow64process2) to determine whether they're running on a system with WOW support.
35
+
An app might place registry keys under the native registry view, or perform functions based on the presence of WOW. The original **IsWow64Process** indicates only whether the app is running on an x64 machine. Apps should now use [IsWow64Process2](/windows/desktop/api/wow64apiset/nf-wow64apiset-iswow64process2) to determine whether they're running on a system with WOW support.
36
36
37
37
## Drivers
38
38
39
-
All kernel-mode drivers, [User-Mode Driver Framework (UMDF)](/windows-hardware/drivers/wdf/overview-of-the-umdf) drivers, and print drivers must be compiled to match the architecture of the OS. If an x86 app has a driver, then that driver must be recompiled for Arm64. The x86 app may run fine under emulation however, its driver will need to be recompiled for Arm64 and any app experience that depends on the driver will not be available. For more info about compiling your driver for Arm64, see [Building Arm64 Drivers with the WDK](/windows-hardware/drivers/develop/building-arm64-drivers).
39
+
All kernel-mode drivers, [User-Mode Driver Framework (UMDF)](/windows-hardware/drivers/wdf/overview-of-the-umdf) drivers, and print drivers must be compiled to match the architecture of the OS. If an x86 app has a driver, then you must recompile that driver for Arm64. The x86 app might run fine under emulation; however, you need to recompile its driver for Arm64 and any app experience that depends on the driver isn't available. For more info about compiling your driver for Arm64, see [Building Arm64 Drivers with the WDK](/windows-hardware/drivers/develop/building-arm64-drivers).
40
40
41
41
## Shell extensions
42
42
43
-
Apps that try to hook Windows components or load their DLLs into Windows processes will need to recompile those DLLs to match the architecture of the system; i.e. Arm64. Typically, these are used by input method editors (IMEs), assistive technologies, and shell extension apps (for example, to show cloud storage icons in Explorer or a rightclick Context menu). To learn how to recompile your apps or DLLs to Arm64, see the [Early preview of Visual Studio support for Windows 10 on Arm development](https://blogs.windows.com/buildingapps/2018/05/08/visual-studio-support-for-windows-10-on-arm-development/) blog post.
43
+
Apps that try to hook Windows components or load their DLLs into Windows processes need to recompile those DLLs to match the architecture of the system, such as Arm64. Typically, input method editors (IMEs), assistive technologies, and shell extension apps use these DLLs. For example, these apps show cloud storage icons in Explorer or a right-click context menu. To learn how to recompile your apps or DLLs to Arm64, see the [Early preview of Visual Studio support for Windows 10 on Arm development](https://blogs.windows.com/buildingapps/2018/05/08/visual-studio-support-for-windows-10-on-arm-development/) blog post.
44
44
45
45
## Debugging
46
46
47
47
To investigate your app's behavior in more depth, see [Debugging on Arm](/windows-hardware/drivers/debugger/debugging-arm64) to learn more about tools and strategies for debugging on Arm.
48
48
49
49
## Virtual Machines
50
50
51
-
The Windows Hypervisor platform is not supported on the Qualcomm Snapdragon 835 Mobile PC Platform. Hence, running virtual machines using Hyper-V will not work. We continue to make investments in these technologies on future Qualcomm chipsets.
51
+
The Windows Hypervisor platform isn't supported on the Qualcomm Snapdragon 835 Mobile PC Platform. Hence, running virtual machines by using Hyper-V doesn't work. We continue to make investments in these technologies on future Qualcomm chipsets.
52
52
53
53
## Dynamic Code Generation
54
54
55
-
X86 desktop apps are emulated on Arm64 by the system generating Arm64 instructions at runtime. This means if an x86 desktop app prevents dynamic code generation or modification in its process, that app cannot be supported to run as x86 on Arm64.
55
+
The system emulates x86 desktop apps on Arm64 by generating Arm64 instructions at runtime. This emulation doesn't support an x86 desktop app that prevents dynamic code generation or modification in its process.
56
56
57
-
This is a security mitigation some apps enable on their process using [SetProcessMitigationPolicy](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-setprocessmitigationpolicy) API with the `ProcessDynamicCodePolicy` flag. To run successfully on Arm64 as an x86 process, this mitigation policy will have to be disabled.
57
+
This security mitigation is enabled on some apps' processes by using the [SetProcessMitigationPolicy](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-setprocessmitigationpolicy) API with the `ProcessDynamicCodePolicy` flag. To run successfully on Arm64 as an x86 process, you need to disable this mitigation policy.
0 commit comments