Edit

Share via

Overview of .NET on Ubuntu

  • Article

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. For more information about available versions, see the Supported distributions section.

Canonical has taken over publishing .NET on Ubuntu. Starting with Ubuntu 22.04, Microsoft no longer distributes .NET for Ubuntu to the Microsoft package repository.

Warning

It's recommended that you choose between either Ubuntu or Microsoft feeds to source .NET packages. Don't mix .NET packages from multiple package repositories, as this leads to problems when apps try to resolve a specific version of .NET.

Method Pros Cons
Package manager
(built-in
Ubuntu feed)
  • Usually the latest version is available.
  • Patches are available right way.
  • Dependencies are included.
  • Easy removal.
  • Available .NET versions are supported for the support period of the particular Ubuntu version.
  • Support for the IBM System Z platform for .NET 8 on Ubuntu 24.04.
  • Not available for Ubuntu 16.04, 18.04, 20.04.
  • .NET versions available vary by Ubuntu version.
  • Preview releases aren't available.
Package manager
(.NET backports
Ubuntu feed)
  • Contains any supported version, which is not contained in the built-in Ubuntu feed.
  • Patches are available right way.
  • Dependencies are included.
  • Easy removal.
  • Compatible with built-in Ubuntu feed.
  • Not available for Ubuntu 16.04, 18.04, 20.04.
  • Requires registering the Ubuntu .NET backports package repository.
  • Preview releases aren't available.
Package manager
(Microsoft feed)
  • Supported versions always available.
  • Patches are available right way.
  • Dependencies are included.
  • Easy removal.
  • Not available for Ubuntu 24.04+.
  • Requires registering the Microsoft package repository.
  • Preview releases aren't available.
  • Only supports x64 Ubuntu.
Script \ Manual extraction
  • Control where .NET is installed.
  • Preview releases are available.
  • Manually install updates.
  • Manually install dependencies.
  • Manual removal.

Considerations when upgrading Ubuntu

Upgrading Ubuntu to 22.04 or later? Consider uninstalling .NET first.

If you used a package manager to install .NET from the Microsoft package repository, you'll end up with a package mix-up problem after upgrading Ubuntu. Now that Canonical publishes .NET to the package feeds for Ubuntu 22.04 (and later versions), the package manager won't know about the previously installed .NET version. The packages can't be upgraded to the latest .NET. First, uninstall them, then reinstall them from the [Ubuntu package repository].

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

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

Important

If you're using .NET 8 SDK and Ubuntu 22.04, understand that SDK versions offered by Canonical are always in the .1xx feature band. If you want to use a newer feature band release, use the Microsoft feed to install the SDK. Make sure you review the information in the .NET package mix ups on Linux article to understand the implications of switching between repository feeds.

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.

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:

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:

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:

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.

Ubuntu Supported .NET versions Available in
built-in Ubuntu feed		 Available in
.NET backports
Ubuntu feed		 Available in
Microsoft feed
24.10 9.0, 8.0 9.0, 8.0 None None
24.04 (LTS) 9.0, 8.0 8.0 9.0, 7.0, 6.0 None
22.04 (LTS) 9.0, 8.0 8.0, 7.0, 6.0 9.0 8.0, 7.0, 6.0, 3.1
20.04 (LTS) 9.0, 8.0 None None 8.0, 7.0. 6.0, 5.0, 3.1, 2.1

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

Tip

You do not need to call apt update. The add-apt-repository command does this by default.

Note

The Ubuntu .NET backports package repository is compatible with the built-in Ubuntu feed. Therefore you do not need to configure your package manager to ignore .NET packages in the built-in Ubuntu feed.

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

Important

Unregistering the Ubuntu .NET backports package repository does not uninstall any packages.

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

Important

This only applies to Ubuntu versions prior to 24.04. Starting with Ubuntu 24.04, Microsoft no longer publishes packages to the Microsoft package repository. Use the supported distributions table to determine the best way to install .NET.

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.

Important

The Microsoft package repository only supports .NET packages that target the x64 architecture. Other architectures, such as Arm, must install .NET by some other means, such as with the installer script or by manual installation.

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

Caution

We recommend that you only use one repository to manage all of your .NET installs. If you've previously installed .NET with the Ubuntu repository, you must clean the system of .NET packages and configure APT to ignore the Ubuntu feeds. For more information about how to do this, see I need a version of .NET that isn't provided by my Linux distribution.

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 which adds the $ID and $VERSION_ID variables
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

Tip

The previous script was written for Ubuntu and might not work if you're using a derived distribution, such as Linux Mint. It's likely that the $ID and $VERSION_ID variables won't be assigned the correct values, making the URI for the wget command invalid. The $ID corresponds to the distribution (e.g., ubuntu), while $VERSION_ID maps to the specific version of Ubuntu you want to get packages for, such as 22.04 or 23.10.

For example, on Ubuntu 22.04 $ID would be ubuntu and $VERSION_ID would be 22.04. The URL would look like: https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb.

You can use a web browser and navigate to https://packages.microsoft.com/config/ubuntu/ to see which versions of Ubuntu are available to use as the $repo_version value.

Install .NET

Important

.NET 9 was released on November 12, 2024. It may take time for the packages to appear in the package manager feeds or for your specific Linux distribution to include it.

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 9.0, use the command sudo apt install dotnet-sdk-9.0. The following table lists the currently supported .NET packages (which might vary by your Ubuntu version):

Product Type Package
9.0 ASP.NET Core Runtime aspnetcore-runtime-9.0
9.0 .NET Runtime dotnet-runtime-9.0
9.0 .NET SDK dotnet-sdk-9.0
8.0 ASP.NET Core Runtime aspnetcore-runtime-8.0
8.0 .NET Runtime dotnet-runtime-8.0
8.0 .NET SDK dotnet-sdk-8.0

Tip

If you're not creating .NET apps, install the ASP.NET Core runtime as it includes the .NET runtime and also supports ASP.NET Core apps.

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:

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-9.0 package with the latest version:

sudo apt update
sudo apt upgrade dotnet-sdk-9.0

Tip

If you've upgraded your Linux distribution since installing .NET, you may need to reconfigure the Microsoft package repository. Run the installation instructions for your current distribution version to upgrade to the appropriate package repository for .NET updates.

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

Important

Using a package manager to install .NET from the Microsoft package feed only supports the x64 architecture. Other architectures, such as Arm, aren't supported by the Microsoft package feed.

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

Unable to locate \ Some packages could not be installed

Note

This information only applies when .NET is installed from the Microsoft package feed.

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:

# Get OS version info which adds the $ID and $VERSION_ID variables
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 must be installed. For more information, see System.Drawing.Common only supported on Windows.

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

Next steps