ubuntu/dotnet-runtime repository overview

⁠Chiselled Ubuntu for dotnet-runtime

Current dotnet-runtime Docker Image from Canonical⁠, based on Ubuntu. Receives security updates and rolls to newer dotnet-runtime or Ubuntu release. This repository is free to use and exempted from per-user rate limits.

⁠About dotnet-runtime

.NET is a free, cross-platform, open source developer platform for building many different types of applications. With .NET, you can use multiple languages, editors, and libraries to build for web, mobile, desktop, games, IoT, and more. Read the .NET documentation⁠ to learn how to deploy your .NET application with container images.

⁠About Chiselled Ubuntu

This image does not include bash nor a package manager nor the .NET SDK. Read more about Chiselled Ubuntu for .NET, a new class of OCI images, on the Ubuntu blog⁠; reading how Canonical and Microsoft partner together to deliver and support .NET on Ubuntu.

If you're looking to publish a self-contained .NET app, please have a look at the ubuntu/dotnet-deps repository. If you're looking to publish an ASP.NET app, please then look at the ubuntu/dotnet-aspnet repository.

⁠Tags and Architectures

Up to 5 years of free security maintenance on LTS channels.

Up to 10 years of customer security maintenance from Canonical's restricted repositories⁠.

Channel Tags shows the most stable channel for that track ordered stable, candidate, beta, edge. More risky channels are always implicitly available. So if beta is listed, you can also pull edge. If candidate is listed, you can pull beta and edge. When stable is listed, all four are available. Images are guaranteed to progress through the sequence edge, beta, candidate before stable.

⁠Commercial use and Extended Security Maintenance channels

If your usage includes commercial redistribution, or requires ESM or unavailable channels/versions, please get in touch with the Canonical team⁠ (or using [email protected]⁠).

⁠Usage

Launch this image locally:

docker run -d --name dotnet-runtime-container -e TZ=UTC -e TZ=UTC ubuntu/dotnet-runtime:8.0-24.04_stable

⁠New entrypoint pebble

Please note that the images tagged 6.0, 8.0 and 9.0-24.10 are Dockerfile-based images, whereas from version 9.0-25.04 onward the images are now rocks. As such the entrypoint is now Pebble. Read more on the Rockcraft docs⁠.

Versions 6.0, 8.0 and 9.0-24.10 images have dotnet as the entrypoint.

$ docker run --rm ubuntu/dotnet-runtime:8.0-24.04_stable
Host:
Version:      8.0.16
...

Versions 9.0-25.04 and later images have pebble enter as the entrypoint. You can access the dotnet with the following command:

$ docker run --rm ubuntu/dotnet-runtime:9.0-25.04_edge exec dotnet
Usage: dotnet [options]
...

The container logs simply show the .NET help message. This is because the container expects a .NET application to be given.

⁠Run a .NET application

Let's use the following HelloWorld application as an example:

⁠Using the images tagged with versions 6.0, 8.0 and 9.0-24.10

$ # Create a HelloWorld.csproj file with the following content
$ cat HelloWorld.csproj
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

# Create a Program.cs file with the following code
$ cat Program.cs
Console.WriteLine("Hello, World!");

# Publish the .NET application (you need the "dotnet8" package)
$ dotnet publish -c Release -o app
MSBuild version 17.8.27+3ab07f0cf for .NET
  Determining projects to restore...
  Restored /tmp/demo/HelloWorld.csproj (in 59 ms).
  HelloWorld -> /tmp/demo/bin/Release/net8.0/HelloWorld.dll
  HelloWorld -> /tmp/demo/bin/Release/net8.0/publish/

# Now you can run the app with "ubuntu/dotnet-runtime:8.0-24.04_stable"
$ docker run --rm -v $PWD/app:/app ubuntu/dotnet-runtime:8.0-24.04_stable /app/HelloWorld.dll
Hello, World!

⁠Using the images tagged with versions 9.0-25.04 and later

Use the same example, but change the TargetFramework to net9.0 in the HelloWorld.csproj file, and then run the following commands:

$ # Publish the .NET application (you need the "dotnet9" package)
$ dotnet publish -c Release -o app
$ docker run --rm -v $PWD/app:/app ubuntu/dotnet-runtime:9.0-25.04_edge exec dotnet /app/HelloWorld.dll
Hello, World!

⁠Build a .NET application image

⁠Using the images tagged 6.0, 8.0 and 9.0-24.10

Here's the same example as above, but for building your own .NET application image, by building the .NET 8 HelloWorld app on Ubuntu 24.04 and packaging it on top of ubuntu/dotnet-runtime:8.0-24.04_stable:

FROM ubuntu:24.04 AS builder

# install the .NET 8 SDK from the Ubuntu archive
# (no need to clean the apt cache as this is an unpublished stage)
RUN apt-get update && apt-get install -y dotnet8 ca-certificates

# add your application code (the HelloWorld example from above)
WORKDIR /source
COPY . .

# publish your .NET app
RUN dotnet publish -c Release -o /app

FROM ubuntu/dotnet-runtime:8.0-24.04_beta

WORKDIR /app
COPY --from=builder /app ./

ENTRYPOINT ["dotnet", "/app/HelloWorld.dll"]

⁠Using the images tagged 9.0-25.04 and later

Here is the example Dockerfile to build your own .NET application image on top of ubuntu/dotnet-runtime:9.0-25.04_edge. You need to replace the net8.0 in the HelloWorld.csproj file with net9.0:

FROM ubuntu:25.04 AS builder

RUN apt-get update && apt-get install -y dotnet9 ca-certificates

# add your application code (the HelloWorld example from above),
# and change the TargetFramework to net9.0 in the HelloWorld.csproj
WORKDIR /source
COPY . .

# publish your .NET app
RUN dotnet publish -c Release -o /app

FROM ubuntu/dotnet-runtime:9.0-25.04_edge

WORKDIR /app
COPY --from=builder /app ./

CMD ["exec", "dotnet", "/app/HelloWorld.dll"]

⁠Debug docs will be automatically generated for the rock-based images.

debug: text: | To debug the container for versions 9.0-25.04 and later:

```bash
docker exec -it dotnet-runtime-container pebble logs
```

⁠Testing/Debugging

To debug the container:

docker logs -f dotnet-runtime-container

⁠Bugs and feature requests

If you find a bug in our image or want to request a specific feature, please file a bug here:

https://bugs.launchpad.net/ubuntu-docker-images/+filebug⁠

Please title the bug "dotnet-runtime: <issue summary>". Make sure to include the digest of the image you are using, from:

docker images --no-trunc --quiet ubuntu/dotnet-runtime:<tag>

⁠Deprecated channels & tags

These channels (tags) are not updated anymore. Please upgrade to newer channels, or reach out⁠ if you can't upgrade.