Install .NET on macOS
In this article, you'll learn how to install .NET on macOS. .NET is made up of the runtime and the SDK. The runtime is used to run a .NET app and may or may not be included with the app. The SDK is used to create .NET apps and libraries. The .NET runtime is always installed with the SDK.
The latest version of .NET is 6.0.
The following table is a list of currently supported .NET releases and the versions of macOS they're supported on. These versions remain supported until the version of .NET reaches end-of-support.
- A ✔️ indicates that the version of .NET is still supported.
- A ❌ indicates that the version of .NET isn't supported.
|Operating System||.NET Core 3.1||.NET 5||.NET 6|
|macOS 12.0 "Monterey"||✔️ 3.1||✔️ 5.0||✔️ 6.0|
|macOS 11.0 "Big Sur"||✔️ 3.1||✔️ 5.0||✔️ 6.0|
|macOS 10.15 "Catalina"||✔️ 3.1||✔️ 5.0||✔️ 6.0|
For more information about the life cycle of .NET releases, see .NET and .NET Core Support Policy.
The following versions of .NET are ❌ no longer supported. The downloads for these still remain published:
- .NET Core 3.0
- .NET Core 2.2
- .NET Core 2.1
- .NET Core 2.0
The runtime is used to run apps created with .NET. When an app author publishes an app, they can include the runtime with their app. If they don't include the runtime, it's up to the user to install the runtime.
There are two different runtimes you can install on macOS:
ASP.NET Core runtime
Runs ASP.NET Core apps. Includes the .NET runtime.
This runtime is the simplest runtime and doesn't include any other runtime. It's highly recommended that you install ASP.NET Core runtime for the best compatibility with .NET apps.
The SDK is used to build and publish .NET apps and libraries. Installing the SDK includes both runtimes: ASP.NET Core and .NET.
Beginning with macOS Catalina (version 10.15), all software built after June 1, 2019 that is distributed with Developer ID, must be notarized. This requirement applies to the .NET runtime, .NET SDK, and software created with .NET.
The runtime and SDK installers for .NET have been notarized since February 18, 2020. Prior released versions aren't notarized. If you run a non-notarized app, you'll see an error similar to the following image:
For more information about how enforced-notarization affects .NET (and your .NET apps), see Working with macOS Catalina Notarization.
.NET applications that use the System.Drawing.Common assembly require libgdiplus to be installed.
An easy way to obtain libgdiplus is by using the Homebrew ("brew") package manager for macOS. After installing brew, install libgdiplus by executing the following commands at a Terminal (command) prompt:
brew update brew install mono-libgdiplus
Install with an installer
macOS has standalone installers that can be used to install the .NET 6 SDK:
Download and manually install
As an alternative to the macOS installers for .NET, you can download and manually install the SDK and runtime. Manual installation is usually performed as part of continuous integration testing. For a developer or user, it's generally better to use an installer.
First, download a binary release for either the SDK or the runtime from one of the following sites. If you install the .NET SDK, you will not need to install the corresponding runtime:
Next, extract the downloaded file and use the
export command to set
DOTNET_ROOT to the extracted folder's location and then ensure .NET is in PATH. This should make the .NET CLI commands available at the terminal.
Alternatively, after downloading the .NET binary, the following commands may be run from the directory where the file is saved to extract the runtime. This will also make the .NET CLI commands available at the terminal and set the required environment variables. Remember to change the
DOTNET_FILE value to the name of the downloaded binary:
DOTNET_FILE=dotnet-sdk-6.0.100-osx-x64.tar.gz export DOTNET_ROOT=$(pwd)/dotnet mkdir -p "$DOTNET_ROOT" && tar zxf "$DOTNET_FILE" -C "$DOTNET_ROOT" export PATH=$PATH:$DOTNET_ROOT
export commands only make the .NET CLI commands available for the terminal session in which it was run.
You can edit your shell profile to permanently add the commands. There are a number of different shells available for Linux and each has a different profile. For example:
- Bash Shell: ~/.bash_profile, ~/.bashrc
- Korn Shell: ~/.kshrc or .profile
- Z Shell: ~/.zshrc or .zprofile
Edit the appropriate source file for your shell and add
:$HOME/dotnet to the end of the existing
PATH statement. If no
PATH statement is included, add a new line with
export DOTNET_ROOT=$HOME/dotnet to the end of the file.
This approach lets you install different versions into separate locations and choose explicitly which one to use by which application.
The following sections describe things you should consider when installing .NET on an Arm-based Mac.
The following table describes which versions of .NET are supported on an Arm-based Mac:
|.NET Version||Architecture||SDK||Runtime||Path conflict|
The x64 and Arm64 versions of the .NET 6 SDK exist independently from each other. If a new version is released, each install needs to be upgraded.
On an Arm-based Mac, all Arm64 versions of .NET are installed to the normal /usr/local/share/dotnet/ folder. However, when you install the x64 version of .NET 6 SDK, it's installed to the /usr/local/share/dotnet/x64/dotnet/ folder.
The x64 .NET 6 SDK installs to its own directory, as described in the previous section. This allows the Arm64 and x64 versions of the .NET 6 SDK to exist on the same machine. However, any x64 SDK prior to 6.0 isn't supported and installs to the same location as the Arm64 version, the /usr/local/share/dotnet/ folder. If you want to install an unsupported x64 SDK, you'll need to first uninstall the Arm64 version. The opposite is also true, you'll need to uninstall the unsupported x64 SDK to install the Arm64 version.
Environment variables that add .NET to system path, such as the
PATH variable, may need to be changed if you have both the x64 and Arm64 versions of the .NET 6 SDK installed. Additionally, some tools rely on the
DOTNET_ROOT environment variable, which would also need to be updated to point to the appropriate .NET 6 SDK installation folder.
Install with Visual Studio for Mac
Visual Studio for Mac installs the .NET SDK when the .NET workload is selected. To get started with .NET development on macOS, see Install Visual Studio 2019 for Mac.
|.NET SDK version||Visual Studio version|
|6.0||Visual Studio 2022 for Mac Preview 3 17.0 or higher.|
|5.0||Visual Studio 2019 for Mac version 8.8 or higher.|
|3.1||Visual Studio 2019 for Mac version 8.4 or higher.|
Install alongside Visual Studio Code
Visual Studio Code is a powerful and lightweight source code editor that runs on your desktop. Visual Studio Code is available for Windows, macOS, and Linux.
While Visual Studio Code doesn't come with an automated .NET installer like Visual Studio does, adding .NET support is simple.
- Download and install Visual Studio Code.
- Download and install the .NET SDK.
- Install the C# extension from the Visual Studio Code marketplace.
Install with bash automation
The script defaults to installing the latest long term support (LTS) version, which is .NET 6.0. You can choose a specific release by specifying the
current switch. Include the
runtime switch to install a runtime. Otherwise, the script installs the SDK.
./dotnet-install.sh --channel 6.0 --runtime aspnetcore
The previous command installs the ASP.NET Core runtime for maximum compatability. The ASP.NET Core runtime also includes the standard .NET runtime.
Containers provide a lightweight way to isolate your application from the rest of the host system. Containers on the same machine share just the kernel and use resources given to your application.
.NET can run in a Docker container. Official .NET Docker images are published to the Microsoft Container Registry (MCR) and are discoverable at the Microsoft .NET Docker Hub repository. Each repository contains images for different combinations of the .NET (SDK or Runtime) and OS that you can use.
Microsoft provides images that are tailored for specific scenarios. For example, the ASP.NET Core repository provides images that are built for running ASP.NET Core apps in production.