.NET Support for macOS 11 and Windows 11 for Arm64 and x64

macOS and Windows Arm64 OSes include support for x64 emulation in addition to native Arm64 execution. This means that these OSes support both Arm64 and x64 apps, and by extension the Arm64 and x64 versions of .NET. The .NET 6 release includes support for macOS and Windows Arm64 OSes, for both native Arm64 execution and x64 emulation. Unintuitively, the majority of the effort for the project wasn't adding support for Arm64 but a large set of changes to support x64 emulation. You can see those changes demonstrated in .NET 6 RC2 Update for macOS and Windows Arm64

The complex nature of the project requires us to explicitly define support for .NET SDKs and runtimes, specifically for .NET on macOS and Windows Arm64.

In terms of operating system support, x64 emulation is a recent feature. It was first introduced (respectively):

• macOS 11 (Big Sur; November 2020)
• Windows 11 (October, 2021)

Note: macOS Arm64 is referred to by Apple as "Apple Silicon" or "M1".

Installation guidance

You are recommended to install the .NET 6 Arm64 SDK on macOS and Windows Arm64. It provides the best experience. The x64 SDK is only recommended for specific use cases, and is typically not needed, even for x64 development. The Arm64 SDK can be used for x64 development.

Note: The key missing scenario is using dotnet test to test with x64 emulation using the Arm64 SDK. At this time, you need to install the x64 SDK to run tests with x64 emulation.

The existing x64 and Arm64 .NET Installers were never built with x64 emulation mind and would clash when installed together. They required changes to support side by side installation. As a result, the existing installers and any existing x64 installations are incompatible with the new .NET 6 Arm64 and x64 installers. Supporting upgrade here is impossible (arm64 would have to remove x64) and doing so partially would make things much more complicated for limited customer benefit.

The following applies only to macOS 11 and Windows 11 Arm64 machines.

• If you have never installed an x64 version of .NET, you are good to go.
• If you have installed an x64 version of .NET (earlier than the supported builds listed below), then you must uninstall or otherwise delete them before installing the new supported builds.
• If you want to be extra careful, uninstall all .NET versions and start with the builds listed below.

On Windows, you can uninstall .NET via "Add or Remove Programs".

On macOS, you must manually delete a .NET installation. The easiest approach is with the following two commands (from the terminal window):

sudo rm -r /usr/local/share/dotnet
sudo rm -r /etc/dotnet

On macOS, you might need to reinstall .NET 6 Arm64 after installing .NET 6 x64 if you previously had x64 installed.

Install directories

On macOS and Windows Arm64, .NET builds install in the following directories, respectively:

Arm64 builds:

• /usr/local/share/dotnet
• C:\Program Files\dotnet

These directories are added to the PATH.

.NET x64 builds:

• /usr/local/share/dotnet/x64
• C:\Program Files\dotnet\x64

These directories are not added to the PATH.

Critical note: That means, if you install a .NET Arm64 build and type dotnet from the terminal (or command prompt), then the Arm64 dotnet launcher will execute. This will not happen for a .NET x64 build, even if it is the only .NET build you install on an Arm64 machine.

Supported Arm64 SDKs

The .NET 6 Arm64 SDK is the first fully-supported Arm64 SDK on macOS 11 and Windows 11 Arm64.

The Arm64 SDK and runtimes install to the dotnet directory, same location the x64 SDK does on an x64 machine.

The following .NET Arm64 SDK builds (and later) are half-supported on Windows Arm64:

• 5.0.403

Half support:

• Can install SDK.
• Can use the templates.
• Can use the runtimes.
• The CLI and toolset (like dotnet build) have not been updated and may have bugs that we are unlikely to fix.

For example, the following command is supported to run an app via x64 emulation with the .NET 6 CLI but not the .NET 5 CLI.

dotnet run -a x64

Supported x64 SDKs

The .NET 6 x64 SDK will be the first fully-supported x64 SDK for both macOS 11 and Windows 11 Arm64.

The x64 SDK and runtimes install to a new x64 directory within the dotnet directory, creating an x64 product hive.

The following .NET x64 SDK builds (and later) are half-supported on macOS Arm64:

• 5.0.403
• 3.1.415

Supported runtimes

All in-support Arm64 and x64 runtimes are supported on macOS and Windows Arm64. We had to change existing installers to install side-by-side with the Arm64 runtimes and SDKs. As a result, none of the existing builds of the runtime are supported. You need to install runtimes released in November 2021 or later.

The following runtime builds (or later) are supported on macOS and Windows Arm64:

• 3.1.21 (x64 only)
• 5.0.12 (x64 only for macOS; Arm64 and x64 for Windows)
• 6.0.0 (x64 and Arm64)

Supported runtimes include:

• .NET Runtime
• ASP.NET Core Runtime
• Windows Desktop Runtime

Unsupported installers

All installers released before November 2021 are not supported on macOS and Windows Arm64.

Where possible, we have added installer blocks into unsupported installers so that users don't accidentally break their .NET installation.

Private installs

You can install any supported .NET version (x64, Arm64, runtime, or SDK) on your macOS and Windows Arm64 machine privately.

For example, on macOS Arm64, you can download and expand a .NET .tar.gz archive to a private location and it should work. The primary challenge we needed to overcome was installing .NET to the global location with the official .NET installers. If you use private installs, then you have a lot more flexibility.

.NET builds for Windows x86

.NET builds for Windows x86 are unaffected by these changes. They are supported on Windows x86, x64, and Arm64 OSes.

However, starting with .NET 6, you can now do the following using the .NET 6 x64 or Arm64 SDK (on Windows):

dotnet run -a x86

This command will launch an app as a 32-bit x86 process, from an x64 or Arm64 SDK.

Notes

Note: None of these changes apply to Linux since its model for x64 emulation on Arm64 is very different. The macOS and Windows models are very similar to one another.

Note: VS Code and Omnisharp support native architecture SDKs, only. Omnisharp does not support x64 SDKs on macOS and Windows Arm64, nor are there plans to support that.

Note: The support model is asymmetric between macOS 11 and Windows 11 Arm64, specifically for .NET 5 and .NET Core 3.1. We have various users on macOS and Windows and are helping them go through this transition to Arm64 with us and are addressing their specific needs.