.NET 10 SDK AOT container images

[richlander]

We plan to publish officially-supported container images for Native AOT in .NET 10. We first offered AOT images with .NET 8 in the nightly branch/repo but never transitioned them to main, making them available and regularly updated but unsupported. We will be publishing SDK AOT images in main and making other cleanup changes in nightly at the same time. These new images will be supported starting with the .NET 10 RC1 release.

The following images will be added to dotnet/sdk:

• 10.0-preview-aot, 10.0-noble-preview-aot
• 10.0-preview-alpine-aot
• 10.0-preview-azurelinux3.0-aot
• 10.0-preview-trixie-aot

These tags will follow our standard practices and policies.

.NET 8 and 9 nightly -aot images will no longer be produced. AOT-specificruntime-deps tags will re-tagged to non-AOT specific tags. No existing images or tags will be deleted.

The intent is to provide supported AOT images to better support Native AOT users while reducing the total cost of publishing AOT images by no longer producing these unsupported .NET 8 and 9 AOT images.

We expect to make these changes with .NET 10 Preview 3. Descriptive workflows with instructions will be provided at that time.

Related

• Provide Officially-Supported .NET AOT Images #5020
• Consider an icu version of aot-deps #4804
• Add .NET 10 AOT SDK images #6298
• Add native AOT runtime-deps and sdk variants #4822
• https://devblogs.microsoft.com/dotnet/the-convenience-of-system-io/

Details

Native AOT is a publishing model that provides significant performance and other benefits. It results in a single-file executable binary that is typically very small and starts fast. It is the publishing model that is the most similar to language platforms like Go and Rust. Native AOT relies on a native toolchain for various aspects of producing an executable binary. Native toolchains are larger and often more difficult to use than the .NET SDK. The -aot SDK images are intended to make it easier to acquire and use a native toolchain, as an implementation detail of dotnet publish.

Scenarios

The images are intended for two primary scenarios:

• Generate a container image including a Native AOT app, using the SDK image in a multi-stage build
• Generate an executable, using the SDK image as a containerized build environment

The .NET SDK offers many ease-of-use capabilties, two of which are relevant here:

1. The SDK can build apps for older .NET versions, enabling .NET 10 SDK to build .NET 8 apps, for example.
2. dotnet publish supports cross-compiling, enabling generating an Arm64 app on an x64 machine, for example.

The first capability is supported for Native AOT in the same way as other publishing methods. While It is possible to use the .NET 10 SDK to produce a .NET 8 app, for example. .NET 10 is not currently supported, per our policies.

Cross-compiling is straightforward for most .NET apps, using some combination of the -a, --os, or -r arguments. For example, we've made it possible to build x64 container images on an Arm64 machine. That's harder with Native AOT due to the dependence on a native toolchain. We don't provide an out-of-the-box solution for that. See releasesapi (sample) and Building native AOT apps in containers for more insight on cross-compilation.

Size

The size of container images is an important consideration. A subset of compressed container image sizes are provided, as reported via Docker Hub tags view. The size were accurate as of March 7th, 2025. Images are all x64. Arm64 sizes will differ.

dotnet/nightly/sdk repo:

Tag	Size (MB)
10.0-preview-alpine	255.53
10.0-preview-alpine-aot	434.2
10.0-preview-noble	308.03
10.0-preview-noble-aot	448.34

dotnet/nightly/runtime-deps repo:

Tag	Size (MB)
8.0-alpine3.21	4.49
8.0-alpine3.21-aot	3.56
8.0-alpine3.21-extra	18.59
8.0-noble	44.42
8.0-noble-chiseled	5.61
8.0-noble-chiseled-aot	4.73
8.0-noble-chiseled-extra	20.41

The size numbers informed the decision that the -aot images were not sufficiently valuable to publish for the runtime-deps repo. Users that want the ~1MB win can produce their own images. We also found that many users require the extra globalization packages in the -extra layer, further limiting the value of the smallest images.

The package differences can be seen with diff:

~/git/dotnet-docker/src/runtime-deps/8.0$ diff alpine3.21-aot/amd64/Dockerfile alpine3.21/amd64/Dockerfile 
18a19
>         libstdc++ \

The difference between the AOT and regular images (needed by CoreCLR apps) is a single package. CoreCLR depends on libstdc++ and Native AOT does not.

~/git/dotnet-docker/src/runtime-deps/8.0$ diff alpine3.21-aot/amd64/Dockerfile alpine3.21-extra/amd64/Dockerfile 
9,11c9
<     DOTNET_RUNNING_IN_CONTAINER=true \
<     # Set the invariant mode since ICU package isn't included (see https://github.com/dotnet/announcements/issues/20)
<     DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=true
---
>     DOTNET_RUNNING_IN_CONTAINER=true
16a15,16
>         icu-data-full \
>         icu-libs \
18a19,20
>         libstdc++ \
>         tzdata \

The difference between aot and extra is two packages. ICU depends on libstdc++, making it a required dependency for Native AOT apps with globalization needs. As a result, the effective difference is zero packages (if globalization functionality is required).

Runtime-deps repo

We will continue to update the -aot tags in the dotnet/nightly/runtime-deps repo. Those tags will be mapped to the same content digest as the slightly larger non-AOT variants.

For the example, the following two tags will be equivalent, the latter provided for compatibility.

• 8.0-alpine3.21
• 8.0-alpine3.21-aot

[steskalja]

Are there any plans for windows server nano containers for native aot

[richlander]

We do not have plans for that. I assume you mean a build image. A key challenge is that we don't have a good way to deliver licensed Visual Studio components.

[surayya-MS]

@richlander do I understand correctly that

1. if I need dotnet/nightly/runtime-deps .NET 8 or 9 AOT image then I can use both aot and non-aot tags?
   (both dotnet/nightly/runtime-deps:9.0.3-noble-chiseled-aot and dotnet/nightly/runtime-deps:9.0.3-noble-chiseled are AOT)
2. For dotnet/nightly/runtime-deps .NET 10 AOT only non-aot tag?
   (dotnet/nightly/runtime-deps:10.0.0-preview.2-noble-chiseled)

[surayya-MS]

Also, if that is true, can i use dotnet/runtime-deps instead of dotnet/nightly/runtime-deps for AOT?

[WeihanLi]

I think the aot container images are mainly for SDK, for build time, we could use alpine or ubuntu image without runtime-deps directly

[lbussell]

You are correct - we will no longer produce any new dotnet/nightly/runtime-deps aot images, for any .NET version (8.0, 9.0, and 10.0). For .NET 8 and 9 we will point the aot tags at the regular runtime-deps images and un-document those tags.

If you want to deploy a .NET 8 or 9 AOT image, you can use the latest version of dotnet/runtime-deps:8.0.X-noble-chiseled or dotnet/runtime-deps:9.0.X-noble-chiseled. Same thing for .NET 10 as well.

The .NET 8 and 9 AOT SDK images will not be updated any more either. To use the non-nightly SDK to build AOT apps you only need to add these packages (for Ubuntu/Debian): clang, llvm, and zlib1g-dev. The .NET 10 AOT SDK Dockerfile is a good example of that.

[alexaka1]

It's still not super clear to me. Could you publish a larger table of what tags are going away or changing, or not expected to be ever tagged?

• dotnet/nightly/runtime-deps:8.0-noble-chiseled-aot is retagged to the non aot manifest.
• dotnet/runtime-deps:10.0-noble-chiseled-aot and dotnet/nightly/runtime-deps:10.0-noble-chiseled-aot will never ever exist. Or does this mean only 10.0 manifests will support aot images going forward? Or does this mean 10.0-aot images will also be retagged to non-aot manifests?
• dotnet/sdk:10.0-aot will exist at GA.

Am I correct?

[richlander]

It appears like you did a correct analysis. You can also look at our tags documentation or query tags in the registry to validate.