How to Install and Manage Multiple .NET Core Versions on macOS Using Homebrew (Brew): A Step-by-Step Guide

Table of Contents#

Prerequisites
Step 1: Install Homebrew
Step 2: Install .NET Core SDK via Homebrew
Step 3: Manage Multiple .NET Core Versions
Step 4: Update .NET Core Versions
Step 5: Uninstall .NET Core Versions
Troubleshooting Common Issues
Conclusion
References

Prerequisites#

Before starting, ensure your system meets these requirements:

macOS Version: macOS 10.15 (Catalina) or later (64-bit).
Internet Connection: Required to download Homebrew and .NET packages.
Terminal Access: Familiarity with basic terminal commands (e.g., cd, ls).

Step 1: Install Homebrew#

If you don’t already have Homebrew installed, follow these steps:

Open Terminal (Applications > Utilities > Terminal).

Run the official Homebrew installation command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen prompts to complete the installation.
Verify Homebrew is installed:
```
brew --version  
```
You should see output like: Homebrew 4.2.0 (version numbers may vary).

Step 2: Install .NET Core SDK via Homebrew#

Homebrew hosts official .NET Core SDK formulas, making installation straightforward. Here’s how to install specific versions or the latest release:

Install the Latest Stable SDK#

To install the latest stable .NET Core SDK (e.g., .NET 8.0 as of 2024):

brew install dotnet-sdk

Install a Specific Version#

To install a specific SDK version (e.g., .NET 6.0 LTS or .NET 7.0), use the versioned formula:

# Install .NET 6.0 LTS  
brew install dotnet-sdk@6  
 
# Install .NET 7.0  
brew install dotnet-sdk@7

Homebrew will:

Download the SDK binaries.
Install them to /usr/local/Cellar/dotnet-sdk/<version> (Intel macOS) or /opt/homebrew/Cellar/dotnet-sdk/<version> (Apple Silicon/M1/M2).
Automatically link the SDK to /usr/local/bin/dotnet (or /opt/homebrew/bin/dotnet for Apple Silicon), ensuring dotnet is in your PATH.

Verify Installation#

Check if the SDK is installed correctly:

dotnet --version

You’ll see the version number (e.g., 8.0.100 for .NET 8.0).

Step 3: Manage Multiple .NET Core Versions#

Once you’ve installed multiple SDKs, use these tools to manage them.

List Installed SDKs#

To see all .NET Core SDKs installed on your system:

dotnet --list-sdks

Example output:

6.0.417 [/usr/local/share/dotnet/sdk]  
7.0.404 [/usr/local/share/dotnet/sdk]  
8.0.100 [/usr/local/share/dotnet/sdk]

Switch Between Versions#

Homebrew uses brew link and brew unlink to manage active versions. To switch between SDKs:

Unlink the current version:

# Replace <version> with the currently active SDK (e.g., 8.0)  
brew unlink dotnet-sdk@8

Link the desired version:
```
# Replace <version> with the target SDK (e.g., 6.0)  
brew link dotnet-sdk@6  
```
Homebrew will update the dotnet symlink to point to the linked version.

Verify the Switch#

Confirm the active SDK version:

dotnet --version  
# Output: 6.0.417 (if linked to .NET 6.0)

Set a Default Version#

To set a permanent default SDK, link it and ensure no other versions are linked. For example, to default to .NET 7.0:

# Unlink all other versions first (if needed)  
brew unlink dotnet-sdk@6  
brew unlink dotnet-sdk@8  
 
# Link the default version  
brew link dotnet-sdk@7

Per-Project Version Control with `global.json`#

For project-specific SDK versions, use .NET’s global.json file (no Homebrew required). This ensures a project uses a specific SDK, even if your system default is different.

Navigate to your project directory:
```
cd /path/to/your/project  
```
Create a global.json file:
```
dotnet new globaljson --sdk-version 7.0.404  
```
Replace 7.0.404 with the SDK version from dotnet --list-sdks.

Verify the project uses the specified SDK:

dotnet --version  
# Output: 7.0.404 (overrides the system default)

Step 4: Update .NET Core Versions#

To update an installed SDK to the latest patch version (e.g., .NET 6.0.417 → 6.0.418):

Update Homebrew’s formula database:
```
brew update  
```

Upgrade the specific SDK:

# Replace <version> with the SDK to update (e.g., 6.0)  
brew upgrade dotnet-sdk@6

Note: Major versions (e.g., 6.0 → 7.0) are separate formulas. To install a new major version, use brew install dotnet-sdk@<new-version>.

Step 5: Uninstall .NET Core Versions#

To remove an unused SDK:

Uninstall the formula:

# Replace <version> with the SDK to remove (e.g., 6.0)  
brew uninstall dotnet-sdk@6

(Optional) Clean up leftover files:
Homebrew removes most files, but check for residuals in:
- /usr/local/share/dotnet/sdk/<version> (Intel)
- /opt/homebrew/share/dotnet/sdk/<version> (Apple Silicon)

Troubleshooting Common Issues#

"dotnet: command not found"#

Cause: The dotnet symlink is missing or PATH is misconfigured.

Fix: Re-link the SDK:

brew link --force dotnet-sdk@<version>

Ensure Homebrew’s bin directory is in your PATH:

# For Intel macOS  
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc  
 
# For Apple Silicon  
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc  
 
# Reload the shell  
source ~/.zshrc

Linking Fails ("Permission denied")#

Cause: Homebrew lacks write permissions for its directories.

Fix: Reset permissions for Homebrew’s cellar:

# For Intel macOS  
sudo chown -R $(whoami) /usr/local/Cellar  
 
# For Apple Silicon  
sudo chown -R $(whoami) /opt/homebrew/Cellar

`dotnet --list-sdks` Doesn’t Show Installed Versions#

Cause: The SDK was installed but not linked properly.