.NET container images

.NET provides various container images for different scenarios. This article describes the different types of images and how they're used. For more information about official images, see the Docker Hub: Microsoft .NET repository.

Tagging scheme

Starting with .NET 8, container images are more pragmatic in how they're differentiated. The following characteristics are used to differentiate images:

• The target framework moniker (TFM) of the app.
• The OS, version, and architecture.
• The image type (for example, runtime, aspnet, sdk).
• The image variant (for example, *-distroless, *-chiseled).
• The image feature (for example, *-aot, *-extra).

Images optimized for size

The following images are focused on resulting in the smallest possible image size:

• Alpine
• Mariner distroless
• Ubuntu chiseled

These images are smaller, as they don't include globalization dependencies such as, ICU, or tzdata. These images only work with apps that are configured for globalization invariant mode. To configure an app for invariant globalization, add the following property to the project file:

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

Images suitable for globalization

Containerized apps that require globalization inflate the image size, as they require globalization dependencies. Ubuntu and Debian images have ICU and tzdata installed already.

The tzdata dependency was added to the following images:

• runtime-deps:8.0-jammy
• runtime-deps:8.0-bookworm-slim

This globalization tactic is used by runtime, aspnet, and sdk images with the same tag.

Some packages are still optional, such as Kerberos, LDAP, and msquic. These packages are only required in niche scenarios.

Scenario-based images

The runtime-deps images have significant value, particularly since they include a standard user and port definitions. They're convenient to use for self-contained and native AOT scenarios. However, solely providing runtime-deps images that are needed by the runtime and sdk images isn't sufficient to enable all the imaginable scenarios or generate optimal images.

The need for runtime-deps extends to native AOT, *-distroless, and *-chiseled image types as well. For each OS, three image variants are provided (all in runtime-deps). Consider the following example using *-chiseled images:

• 8.0-jammy-chiseled: Images for Core CLR, no tzdata or ICU.
• 8.0-jammy-chiseled-aot: Images for native AOT, no tzdata, ICU, or stdc++.
• 8.0-jammy-chiseled-extra: Image for both Core CLR and native AOT, includes tzdata, ICU, and stdc++.

In terms of scenarios:

The 8.0-jammy-chiseled images are the base for runtime and aspnet images of the same tag. By default, native AOT apps can use the 8.0-jammy-chiseled-aot image, since it's optimized for size. Native AOT apps and Core CLR self-contained/single file apps that require globalization functionality can use 8.0-jammy-chiseled-extra.

Alpine and Mariner images use the same scheme.

Native AOT container images

Native AOT images are published to the sdk repository, and tagged with the -aot suffix. These images enable building native AOT apps. They're created for distros with matching runtime-deps:*-aot images. These images are large, commonly twice the size of regular SDK images.

AOT images are published for:

• Alpine
• Mariner
• Ubuntu

For more information, see Native AOT deployment

Docker hub repositories

All of the official Microsoft images for .NET are published to the microsoft-dotnet Docker Hub organization. Consider the following repositories.

.NET stable image repositories:

.NET nightly image repositories:

.NET Framework image repositories:

See also

• What's new in .NET 8: Container images
• New approach for differentiating .NET 8+ images