.NET Image Variants

.NET container images offer several image variants.

.NET images for Ubuntu, Debian, Azure Linux, Windows Server Core, and Nano Server images are full-featured and include ICU and time zone libraries which provide full Unicode and globalization support. These images are intended to satisfy the most common use cases of .NET developers.

Alpine and Ubuntu Chiseled .NET images are focused on size. By default, these images do not include icu or tzdata, meaning that these images only work with apps that are configured for globalization-invariant mode. Apps that require globalization support can use the extra image variant of the dotnet/runtime-deps images. Because this is only available with runtime-deps images, it requires a self-contained deployment of the application. Alpine, Azure Linux, and Ubuntu Chiseled images also come in extra, composite, and aot variants (see below).

Distroless

Ubuntu Chiseled and Azure Linux distroless .NET images contain only the minimum set of libraries necessary to run .NET applications with everything else removed. For more information, see the distroless .NET images documentation.

extra (.NET 8+)

For apps that depend on globalization functionality, the extra image variant is offered for Ubuntu Chiseled and Azure Linux distroless runtime-deps, runtime, and aspnet images as well as runtime-deps images for Alpine Linux. These extra images contain everything that the default images do, plus icu and tzdata.

composite (.NET 8+)

ASP.NET Core Composite images provide a smaller size on disk while keeping the performance of the default ReadyToRun (R2R) setting. The caveat is that the composite images have tighter version coupling. This means the final app run on them cannot use handpicked custom versions of the framework and/or ASP.NET assemblies that are built into the composite binary. For a full technical description on how the composites work, we have a feature doc here.

aot (.NET 10+, SDK-only)

SDK images with the -aot suffix include additional libraries required for native AOT compilation that aren't present in the default mcr.microsoft.com/dotnet/sdk images.

Native AOT compilation produces an app that's self-contained and that has been ahead-of-time (AOT) compiled to native code. Native AOT apps have faster startup time and smaller memory footprints. Native AOT apps can be deployed on the standard mcr.microsoft.com/dotnet/runtime-deps images. See "Limitations of Native AOT deployment" to see if your app might be compatible.