Install .NET on macOS
In this article, you 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 might or might 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 8.
Supported releases
There are two types of supported releases: Long Term Support (LTS) releases and Standard Term Support (STS) releases. The quality of all releases is the same. The only difference is the length of support. LTS releases get free support and patches for three years. STS releases get free support and patches for 18 months. For more information, see .NET Support Policy.
The following table is a list of currently supported .NET releases and the versions of macOS they're supported on:
Operating System | .NET 8 (LTS) | .NET 6 (LTS) |
---|---|---|
macOS 14.0 "Sonoma" | ✔️ 8.0 | ✔️ 6.0 |
macOS 13.0 "Ventura" | ✔️ 8.0 | ✔️ 6.0 |
macOS 12.0 "Monterey" | ✔️ 8.0 | ✔️ 6.0 |
macOS 11.0 "Big Sur" | ❌ | ✔️ 6.0 |
macOS 10.15 "Catalina" | ❌ | ✔️ 6.0 |
For a full list of .NET versions and their support life cycle, see .NET Support Policy.
Unsupported releases
The following versions of .NET are ❌ no longer supported:
- .NET 7
- .NET 5
- .NET Core 3.1
- .NET Core 3.0
- .NET Core 2.2
- .NET Core 2.1
- .NET Core 2.0
Runtime information
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..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.
SDK information
The SDK is used to build and publish .NET apps and libraries. Installing the SDK includes both runtimes: ASP.NET Core and .NET.
Notarization
Beginning with macOS Catalina (version 10.15), all software built after June 1, 2019 that's 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.
libgdiplus
.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
Automated install
macOS has standalone installers that can be used to install .NET:
Manual 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.
Download a binary release for either the SDK or the runtime from one of the following sites. The .NET SDK includes the corresponding runtime:
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. Exporting DOTNET_ROOT
makes the .NET CLI commands available in the terminal. For more information about .NET environment variables, see .NET SDK and CLI environment variables.
Different versions of .NET can be extracted to the same folder, which coexist side-by-side.
Example
The following commands use Bash to set the environment variable DOTNET_ROOT
to the current working directory followed by .dotnet
. That directory is created if it doesn't exist. The DOTNET_FILE
environment variable is the filename of the .NET binary release you want to install. This file is extracted to the DOTNET_ROOT
directory. Both the DOTNET_ROOT
directory and its tools
subdirectory are added to the PATH
environment variable.
Important
If you run these commands, remember to change the DOTNET_FILE
value to the name of the .NET binary you downloaded.
DOTNET_FILE=dotnet-sdk-8.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
You can install more than one version of .NET in the same folder.
You can also install .NET to the home directory identified by the HOME
variable or ~
path:
export DOTNET_ROOT=$HOME/.dotnet
Verify downloaded binaries
After downloading an installer, verify it to make sure that the file hasn't been changed or corrupted. You can verify the checksum on your computer and then compare it to what was reported on the download website.
When you download an installer or binary from an official download page, the checksum for the file is displayed. Select the Copy button to copy the checksum value to your clipboard.
Use the sha512sum
command to print the checksum of the file you've downloaded. For example, the following command reports the checksum of the dotnet-sdk-8.0.100-linux-x64.tar.gz file:
$ sha512sum dotnet-sdk-8.0.100-linux-x64.tar.gz
13905ea20191e70baeba50b0e9bbe5f752a7c34587878ee104744f9fb453bfe439994d38969722bdae7f60ee047d75dda8636f3ab62659450e9cd4024f38b2a5 dotnet-sdk-8.0.100-linux-x64.tar.gz
Compare the checksum with the value provided by the download site.
Important
Even though a Linux file is shown in these examples, this information equally applies to macOS.
Use a checksum file to validate
The .NET release notes contain a link to a checksum file you can use to validate your downloaded file. The following steps describe how to download the checksum file and validate a .NET install binary:
The release notes page for .NET 8 on GitHub at https://github.com/dotnet/core/tree/main/release-notes/8.0 contains a section named Releases. The table in that section links to the downloads and checksum files for each .NET 8 release:
Select the link for the version of .NET that you downloaded. The previous section used .NET SDK 8.0.100, which is in the .NET 8.0.0 release.
In the release page, you can see the .NET Runtime and .NET SDK version, and a link to the checksum file:
Copy the link to the checksum file.
Use the following script, but replace the link to download the appropriate checksum file:
curl -O https://dotnetcli.blob.core.windows.net/dotnet/checksums/8.0.0-sha.txt
With both the checksum file and the .NET release file downloaded to the same directory, use the
sha512sum -c {file} --ignore-missing
command to validate the downloaded file.When validation passes, you see the file printed with the OK status:
$ sha512sum -c 8.0.0-sha.txt --ignore-missing dotnet-sdk-8.0.100-linux-x64.tar.gz: OK
If you see the file marked as FAILED, the file you downloaded isn't valid and shouldn't be used.
$ sha512sum -c 8.0.0-sha.txt --ignore-missing dotnet-sdk-8.0.100-linux-x64.tar.gz: FAILED sha512sum: WARNING: 1 computed checksum did NOT match sha512sum: 8.0.0-sha.txt: no file was verified
Set environment variables system-wide
If you used the instructions in the Manual install example section, the variables set only apply to your current terminal session. Add them to your shell profile. There are many different shells available for macOS and each has a different profile. For example:
- Bash Shell: ~/.profile, /etc/profile
- Korn Shell: ~/.kshrc or .profile
- Z Shell: ~/.zshrc or .zprofile
Set the following two environment variables in your shell profile:
DOTNET_ROOT
This variable is set to the folder .NET was installed to, such as
$HOME/.dotnet
:export DOTNET_ROOT=$HOME/.dotnet
PATH
This variable should include both the
DOTNET_ROOT
folder and theDOTNET_ROOT/tools
folder:export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools
Arm-based Macs
The following sections describe things you should consider when installing .NET on an Arm-based Mac.
What's supported
The following table describes which versions of .NET are supported on an Arm-based Mac:
.NET Version | SDK | Runtime | Path conflict |
---|---|---|---|
8 | Yes | Yes | No |
8 | Yes | Yes | No |
6 | Yes | Yes | No |
6 | Yes | Yes | No |
The x64 and Arm64 versions of the .NET SDK exist independently from each other. If a new version is released, each install needs to be upgraded.
Path differences
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 SDK, it's installed to the /usr/local/share/dotnet/x64/dotnet/ folder.
Path conflicts
The x64 .NET SDK installs to its own directory, as described in the previous section. This allows the Arm64 and x64 versions of the .NET SDK to exist on the same machine. However, any x64 SDK prior to .NET 6 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 need to first uninstall the Arm64 version. The opposite is also true, you need to uninstall the unsupported x64 SDK to install the Arm64 version.
Path variables
Environment variables that add .NET to system path, such as the PATH
variable, might 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 2022 for Mac.
Important
Visual Studio for Mac is being retired. For more information, see What's happening to Visual Studio for Mac?.
.NET SDK version | Visual Studio version |
---|---|
8.0 | Visual Studio 2022 for Mac 17.6.1 or higher. (Available as a preview feature only.) |
6.0 | Visual Studio 2022 for Mac 17.0 or higher. |
Important
Microsoft has announced the retirement of Visual Studio for Mac. Visual Studio for Mac will no longer be supported starting August 31, 2024. Alternatives include:
- Visual Studio Code with the C# Dev Kit and related extensions, such as .NET MAUI and Unity.
- Visual Studio running on Windows in a VM on Mac.
- Visual Studio running on Windows in a VM in the Cloud.
For more information, see Visual Studio for Mac retirement announcement.
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 dotnet-install scripts are used for automation and non-admin installs of the runtime. You can download the script from the dotnet-install script reference page.
The script defaults to installing the latest long term support (LTS) version, which is .NET 8. You can choose a specific release by specifying the channel
switch. Include the runtime
switch to install a runtime. Otherwise, the script installs the SDK.
The following command installs the ASP.NET Core runtime for maximum compatibility. The ASP.NET Core runtime also includes the standard .NET runtime.
./dotnet-install.sh --channel 8.0 --runtime aspnetcore
To learn how to use the .NET CLI, see .NET CLI overview.
Docker
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.
Microsoft provides images that are tailored for specific scenarios. Each repository contains images for different combinations of the .NET (SDK or Runtime) and OS that you can use. For example, the ASP.NET Core repository provides images that are built for running ASP.NET Core apps in production.
For more information about using .NET in a Docker container, see Introduction to .NET and Docker and Samples.