Overview of .NET on Ubuntu

This article describes how to install .NET on Ubuntu. Starting with Ubuntu 22.04, most supported versions of .NET are available in the built-in Ubuntu feed. The Ubuntu .NET backports package repository contains the remaining supported .NET versions, which are not available in the built-in Ubuntu package feed for these Ubuntu versions. For more information about available versions, see the Supported distributions section. Additionally, for Ubuntu 23.10 and previous versions, the Microsoft package repository contains every version of .NET that is currently, or was previously, supported.

Decide how to install .NET

When your version of Ubuntu supports .NET through the built-in or .NET backports Ubuntu feed, support for those builds of .NET is provided by Canonical and the builds might be optimized for different workloads. Microsoft provides support for packages in the Microsoft package repository feed.

Use the following sections to determine how you should install .NET:

• I'm using Ubuntu 22.04 or later, and I only need .NET
• I'm using a version of Ubuntu prior to 22.04
• I'm using other Microsoft packages, such as powershell, mdatp, or mssql
• I want to create a .NET app
• I want to run a .NET app in a container, cloud, or continuous-integration scenario
• My Ubuntu distribution doesn't include the .NET version I want, or I need an out-of-support .NET version
• I want to install a preview version
• I don't want to use APT
• I'm using an Arm-based CPU
• I'm using the IBM System Z platform

I'm using Ubuntu 22.04 or later, and I only need .NET

Install .NET through the Ubuntu feed. For more information, see the following pages:

• Install .NET on Ubuntu 24.04.
• Install .NET on Ubuntu 23.10.
• Install .NET on Ubuntu 23.04.
• Install .NET on Ubuntu 22.04.

If you're going to install the Microsoft repository to use other Microsoft packages, such as powershell, mdatp, or mssql, you need to deprioritize the .NET packages provided by the Microsoft repository. For instructions on how to deprioritize the packages, see My Linux distribution provides .NET packages, and I want to use them.

I'm using a version of Ubuntu prior to 22.04

Use the instructions on the version-specific Ubuntu page.

• 20.04 (LTS)
• 18.04 (LTS)
• 16.04 (LTS)

Review the Supported distributions section for more information about what versions of .NET are supported for your version of Ubuntu. If you're installing a version that isn't supported, see Register the Microsoft package repository.

I'm using other Microsoft packages, such as powershell, mdatp, or mssql

If your Ubuntu version supports .NET through an Ubuntu feeds, you must decide which feed should install .NET. The Supported distributions section provides a table that lists which versions of .NET are available in the package feeds.

If you want to source the .NET packages from an Ubuntu feed, you need to deprioritize the .NET packages provided by the Microsoft repository. For instructions on how to deprioritize the packages, see My Linux distribution provides .NET packages, and I want to use them.

I want to create a .NET app

Use the same package sources for the SDK as you use for the runtime. It is recommended that you install .NET through an Ubuntu feed. If, however you want to install .NET from another source (e.g. the Microsoft package repository to access higher SDK feature bands), you should uninstall .NET, configure your package manager to ignore .NET packages from the Ubuntu feed and reinstall it from the other source.

Review the other suggestions in the Decide how to install .NET section.

I want to run a .NET app in a container, cloud, or continuous-integration scenario

If your Ubuntu version provides the .NET version you require, install it from an Ubuntu feed. Otherwise, register the Microsoft package repository and install .NET from that repository. Review the information in the Supported distributions section.

If the version of .NET you want isn't available, try using the dotnet-install script.

My Ubuntu distribution doesn't include the .NET version I want, or I need an out-of-support .NET version

We recommend you use APT and the Microsoft package repository. For more information, see the Register and install with the Microsoft package repository section.

I want to install a preview version

Use one of the following ways to install .NET:

• Install .NET with install-dotnet script.
• Manually install .NET

I don't want to use APT

If you want an automated installation, use the Linux installation script.

If you want full control over the .NET installation experience, download a tarball and manually install .NET. For more information, see Manual install.

I'm using an Arm-based CPU

If your Ubuntu version provides the .NET version you require, install it from the built-in feed. Review the information in the Supported distributions section.

If the version of .NET you want isn't available, try using one of the following ways to install .NET:

• Install .NET with install-dotnet script.
• Manually install .NET

I'm using the IBM System Z platform

Starting with .NET 8 on Ubuntu 24.04, Canonical supports .NET for the IBM System Z platform. Canonical works on extending the support to other .NET and Ubuntu versions.

Install .NET through the built-in Ubuntu feed. For more information, see the following page:

• Install .NET 8 on Ubuntu 24.04.

Supported distributions

The following table is a list of currently supported .NET releases and the versions of Ubuntu they're supported on. Each link goes to the specific Ubuntu version page with specific instructions on how to install .NET for that version of Ubuntu.

When an Ubuntu version reaches the end of its support period, .NET is no longer supported with that particular Ubuntu version.

Canonical supports .NET versions in the built-in Ubuntu feed for the lifetime of that Ubuntu version, even beyond the Microsoft-provided support lifetime and provides best-effort support for .NET versions in the .NET backports package repository, which does not extend beyond the Microsoft-provided support lifetime.

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

Ubuntu .NET backports package repository

The Ubuntu .NET backports package repository provides versions of .NET, which are not available in the built-in Ubuntu feed. The Supported distributions section provides a table that lists which versions of .NET are available in the package feed. Canonical maintains the packages contained in this package repository and provides best-effort support, which does not extend beyond the Microsoft-provided support lifetime or the support period of the particular Ubuntu version.

See the web-view of the Ubuntu .NET backports package repository for more details.

Register the Ubuntu .NET backports package repository

Open a terminal and run the following command:

sudo add-apt-repository ppa:dotnet/backports

Unregister the Ubuntu .NET backports package repository

If you no longer want to consume packages from the Ubuntu .NET backports package repository you can unregister it. Open a terminal and run the following command:

sudo add-apt-repository --remove ppa:dotnet/backports

add-apt-repository command not found

The add-apt-repository(1) utility is pre-installed on most Ubuntu installations.

If you receive an error message that the add-apt-repository command was not found, you have to install the software-properties-common package, which provides this command. Open a terminal and run the following commands:

sudo apt update
sudo apt install software-properties-common

Register the Microsoft package repository

The Microsoft package repository contains all versions of .NET that were previously, or are currently, supported with your version of Ubuntu. If your version of Ubuntu provides .NET packages, you'll need to deprioritize the Ubuntu packages and use the Microsoft repository. For instructions on how to deprioritize the packages, see I need a version of .NET that isn't provided by my Linux distribution.

Preview releases are not available in the Microsoft package repository. For more information, see Install preview versions.

Installing with APT can be done with a few commands. Before you install .NET, run the following commands to add the Microsoft package signing key to your list of trusted keys and add the package repository.

Open a terminal and run the following commands:

# Get OS version info
source /etc/os-release

# Download Microsoft signing key and repository
wget https://packages.microsoft.com/config/$ID/$VERSION_ID/packages-microsoft-prod.deb -O packages-microsoft-prod.deb

# Install Microsoft signing key and repository
sudo dpkg -i packages-microsoft-prod.deb

# Clean up
rm packages-microsoft-prod.deb

# Update packages
sudo apt update

Install .NET

After you've registered the Microsoft package repository, or if the Ubuntu Feeds supports the .NET package for your Ubuntu version, you can install .NET through the package manager with the sudo apt install <package-name> command. Replace <package-name> with the name of the .NET package you want to install. For example, to install .NET SDK 8.0, use the command sudo apt install dotnet-sdk-8.0. The following table lists the currently supported .NET packages:

If you want to install an unsupported version of .NET, check the Supported distributions section to see if that version of .NET is available. Then, substitute the version of .NET you want to install. For example, to install ASP.NET Core 8.0, use the package name aspnetcore-runtime-8.0.

Some environment variables affect how .NET is run after it's installed. For more information, see .NET SDK and CLI environment variables.

Uninstall .NET

If you installed .NET through a package manager, uninstall in the same way with the apt-get remove command:

sudo apt-get remove dotnet-sdk-6.0

For more information, see Uninstall .NET.

Install preview versions

Preview and release candidate versions of .NET aren't available in package repositories. You can install previews and release candidates of .NET in one of the following ways:

• Scripted install with install-dotnet.sh
• Manual binary extraction

Remove preview versions

When using a package manager to manage your installation of .NET, you may run into a conflict if you've previously installed a preview release. The package manager may interpret the non-preview release as an earlier version of .NET. To install the non-preview release, first uninstall the preview versions. For more information about uninstalling .NET, see How to remove the .NET Runtime and SDK.

Use APT to update .NET

If you installed .NET through a package manager, you can upgrade the package with the apt upgrade command. For example, the following commands upgrade the dotnet-sdk-8.0 package with the latest version:

sudo apt update
sudo apt upgrade dotnet-sdk-8.0

Troubleshooting

Starting with Ubuntu 22.04, you might run into a situation where it seems only a piece of .NET is available. For example, you've installed the runtime and the SDK, but when you run dotnet --info only the runtime is listed. This situation can be related to using two different package sources. The built-in Ubuntu 22.04 and Ubuntu 22.10 package feeds include some versions of .NET, but not all, and you might have also installed .NET from the Microsoft feeds. For more information about how to fix this problem, see Troubleshoot .NET errors related to missing files on Linux.

APT problems

This section provides information on common errors you might get while using APT to install .NET.

Unable to find package

For more information on installing .NET without a package manager, see one of the following articles:

• Use the install-dotnet script to install .NET.
• Manually install .NET.

Unable to locate \ Some packages could not be installed

If you receive an error message similar to Unable to locate package {dotnet-package} or Some packages could not be installed, run the following commands.

There are two placeholders in the following set of commands.

• {dotnet-package}
  This represents the .NET package you're installing, such as aspnetcore-runtime-8.0. This is used in the following sudo apt-get install command.

First, try purging the package list:

sudo dpkg --purge packages-microsoft-prod && sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update

Then, try to install .NET again. If that doesn't work, you can run a manual install with the following commands:

If you're using Ubuntu 23.10 or later, try the following commands:

# Define the OS version, name, and codename
source /etc/os-release

# Download the Microsoft keys
sudo apt-get install -y gpg wget
wget https://packages.microsoft.com/keys/microsoft.asc
cat microsoft.asc | gpg --dearmor -o microsoft.asc.gpg

# Add the Microsoft repository to the system's sources list
wget https://packages.microsoft.com/config/$ID/$VERSION_ID/prod.list
sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list

# Move the key to the appropriate place
sudo mv microsoft.asc.gpg $(cat /etc/apt/sources.list.d/microsoft-prod.list | grep -oP "(?<=signed-by=).*(?=\])")

# Update packages and install .NET
sudo apt-get update && \
  sudo apt-get install -y {dotnet-package}

If you're using an Ubuntu version prior to 23.10, try the following commands:

# Define the OS version, name, and codename
source /etc/os-release

# Download the Microsoft keys
sudo apt-get install -y gpg wget
wget https://packages.microsoft.com/keys/microsoft.asc
cat microsoft.asc | gpg --dearmor -o microsoft.asc.gpg
sudo mv microsoft.asc.gpg /etc/apt/trusted.gpg.d/

# Add the Microsoft repository to the system's sources list
wget https://packages.microsoft.com/config/$ID/$VERSION_ID/prod.list
sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list

# Set ownership
sudo chown root:root /etc/apt/trusted.gpg.d/microsoft.asc.gpg
sudo chown root:root /etc/apt/sources.list.d/microsoft-prod.list

# Update packages and install .NET
sudo apt-get update && \
  sudo apt-get install -y {dotnet-package}

Failed to fetch

While installing the .NET package, you may see an error similar to Failed to fetch ... File has unexpected size ... Mirror sync in progress?. This error could mean that the package feed for .NET is being upgraded with newer package versions, and that you should try again later. During an upgrade, the package feed shouldn't be unavailable for more than 30 minutes. If you continually receive this error for more than 30 minutes, please file an issue at https://github.com/dotnet/core/issues.

Dependencies

When you install with a package manager, these libraries are installed for you. But, if you manually install .NET or you publish a self-contained app, you must install these dependencies to run your app:

• ca-certificates
• libc6
• libgcc1 (for 16.x and 18.x)
• libgcc-s1 (for 20.x or later)
• libgssapi-krb5-2
• libicu55 (for 16.x)
• libicu60 (for 18.x)
• libicu66 (for 20.x)
• libicu70 (for 22.04)
• libicu72 (for 23.10)
• libicu74 (for 24.04 or later)
• liblttng-ust1 (for 22.x or later)
• libssl1.0.0 (for 16.x)
• libssl1.1 (for 18.x, 20.x)
• libssl3 (for 22.x or later)
• libstdc++6
• libunwind8 (for 22.x or later)
• zlib1g

Dependencies can be installed with the apt install command. The following snippet demonstrates installing the zlib1g library:

sudo apt install zlib1g

If the .NET app uses the System.Drawing.Common assembly, libgdiplus will also need to be installed. Because System.Drawing.Common is no longer supported on Linux, this only works on .NET 6 and requires setting the System.Drawing.EnableUnixSupport runtime configuration switch.

You can install a recent version of libgdiplus by adding the Mono repository to your system.

Next steps

• .NET CLI overview
• How to enable Tab completion for the .NET CLI
• Tutorial: Create a console application with .NET SDK using Visual Studio Code