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

[richlander]

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

[artl93]

@richlander - There directories are not added to the PATH. << Their?

[NatMarchand]

Hi there!
Thanks for the post, we tried yesterday to make dotnet 6 work with a colleague on her Mac M1 and were unable to do so, hopefully it will help us to get there.
However, we're unable to find a link to download the mentioned sdks :

• 5.0.403
• 3.1.415
  I guess they'll be available soon but can't we download a preview of them ?

[richlander]

@artl93 -- Oops. Fixed that. Thanks.

@NatMarchand -- Sorry about that. Those builds are not yet released. They will be released at the same time as the .NET 6 final build. I updated to text to clarify.

[hdamasceno]

After install the new version, nothing the console CLI not works!
Is this issue only with me?

My Mac is updated and before I install the new version 6.0.100 was everything OK

[marinasundstrom]

I have never got this to work either on my M1 Mac. I need older versions in order to run tools that target those frameworks, like Tye.

[danmoseley]

@hdamasceno @RobertSundstrom what are your symptoms/setup -- can you share more info?

[richlander]

In particular, can you share which versions of .NET you have on your machine?

[eluchsinger]

Also having issues here. By the way can you make this documentation available somewhere more public? Finding this in GitHub is not the best way to go with such an important information.

Reproduction Steps:

• First uninstalled the existing .NET installations according to this guidance.
• On my Mac (Apple Silicon) I installed .NET 6 (ARM). dotnet works.
• I installed .NET 5 (x64). dotnet stopped working - it's not found.
• Installed .NET 6 (ARM) again - dotnet command is found, but I only see the ARM runtimes / SDKs (I don't know how I can't make it show the x64 ones anymore - dotnet -a x64 --list-sdks does not work.
• Trying to run a project now using Rider, I get the error: Failed to load /usr/local/share/dotnet/host/fxr/6.0.0/libhostfxr.dylib,

[marinasundstrom]

@danmoseley Now it seems to work. All the older versions, new installers, have been put in the x64 directory.

Tye (.NET 3.1 x64 self-contained, I believe) seems to run, at least. It runs a build on my broken project ☺️

The problem could have been that the necessary files were missing in /etc/dotnet. I had not deleted the directory before.

I will try this further and see what does work and not work. Hopefully, all of my stuff will.

The latest version of VS for Mac 2022 (Preview 3) defaults to ARM64. That is great.

One annoying thing, that someone else pointed out, is that the dotnet --list-sdks command does not show any of the x64 SDKs.

Better user experience and documentation is needed. Not simply dev docs on GitHub.

[eluchsinger]

How am I supposed now to run the dotnet x64 version? I get a warning about the development certificates when running my .NET 5 project. Running the dotnet dev-certs https --trust command doesn't help - probably because that command uses the ARM version dotnet.

How can I run dotnet in the x64 mode when I have both ARM and x64 installed?

After uninstalling all .NET Versions and reinstalling .NET 5, now it is in the x64 folder and the command dotnet can not be found. Probably adding the x64 folder to PATH will fix this problem, but then I will have a whole lot of other issues as soon as I install .NET 6 again.

Right now I will defer installing or migrating to .NET 6 until these issues are fixed or a clear guidance is provided.

[Serge-N]

No luck for me here. Such a pain. Dotnet 6 (Arm64) runs just fine. The moment one installs dotnet 3 (x64) and dotnet 5 (x64). The last to install become the default.

For now, I will resort to running the ARM version and try to get only runtimes for dotnet 3 and 6.