Docker makes it easy to package an application and run the same image across different environments. The problem starts when the machines running those containers use different CPU architectures.
An application developed on an ARM64 laptop may work perfectly on that machine but fail when the same Docker image is deployed to an x64 server. The reverse can happen when an image is built on an x64 CI runner and later deployed to an ARM64 environment.
The application code may be identical. The difference is the CPU architecture used by the container image.
For modern development environments, supporting both ARM64 and x64 is increasingly useful. Developers may use ARM-based laptops, while CI systems, cloud virtual machines, and existing servers may still use x64 infrastructure.
The practical solution is to build a multi-platform Docker image.
This article explains the architecture differences, how Docker handles multi-platform images, how to build them from a .NET application, and the common problems that appear when native dependencies are involved.
ARM64 and x64 Are Different Architectures
The two architectures use different instruction sets.
ARM64 is commonly found in:
ARM-based laptops
Cloud ARM instances
Mobile and embedded devices
Development boards
x64, also called amd64, is common on:
Traditional Intel servers
AMD servers
Many CI runners
Existing cloud infrastructure
A Docker image built specifically for one architecture is not automatically compatible with another.
For example:
Application Image
|
+---- linux/amd64
|
+---- linux/arm64These are different image variants.
Docker can present them under one image tag using a multi-platform manifest.
What Is a Multi-Platform Image?
A multi-platform image contains references to different platform-specific image manifests.
For example:
myapp:latest
|
+---- linux/amd64
|
+---- linux/arm64When an ARM64 machine pulls the image:
docker pull myapp:latestDocker selects the ARM64 variant.
When an x64 machine pulls the same tag, Docker selects the x64 variant.
The application developer does not need to maintain separate image names such as:
myapp-amd64
myapp-arm64Instead, one logical image tag can represent multiple architectures.
Why a Normal Docker Build Can Cause Problems
Consider this Dockerfile:
FROM mcr.microsoft.com/dotnet/aspnet:latest
WORKDIR /app
COPY ./publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]If this image is built on an x64 machine:
docker build -t myapp .the resulting image can be architecture-specific.
Moving it to an ARM64 machine may result in an error similar to an architecture mismatch.
The important distinction is:
Dockerfile
|
v
Build environment architecture
|
v
Image architectureThe Dockerfile itself does not automatically make the output multi-platform.
Check the Architecture of Your Current Machine
Before troubleshooting, check the host architecture:
docker versionYou can also inspect the system:
uname -mTypical output may look like:
x86_64or:
aarch64Docker can also report the architecture of an image:
docker image inspect myappFor a more convenient inspection of a published image:
docker buildx imagetools inspect myapp:latestA multi-platform image should show entries for the architectures it supports.
Use Docker Buildx
Docker Buildx provides the tooling needed to build images for multiple platforms.
A typical command is:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t myregistry.example.com/myapp:latest \
--push .The important option is:
--platform linux/amd64,linux/arm64It tells Docker to build variants for both architectures.
The result is one image tag with multiple platform-specific manifests.
Why --push Matters
A multi-platform build normally needs to be pushed to a registry so the registry can store the platform-specific manifests and layers.
For example:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t myregistry.example.com/myapp:1.0 \
--push .After pushing, an ARM64 machine can pull the same tag:
docker pull myregistry.example.com/myapp:1.0Docker selects the appropriate image.
An x64 machine can use the exact same command.
Build a .NET Application for Multiple Architectures
A simple multi-stage .NET Dockerfile might look like this:
FROM mcr.microsoft.com/dotnet/sdk:latest AS build
WORKDIR /src
COPY ["MyApp/MyApp.csproj", "MyApp/"]
RUN dotnet restore "MyApp/MyApp.csproj"
COPY . .
WORKDIR "/src/MyApp"
RUN dotnet publish \
"MyApp.csproj" \
-c Release \
-o /app/publish \
--no-restore
FROM mcr.microsoft.com/dotnet/aspnet:latest AS final
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]The important point is that the base images also need to support the target architectures.
If the .NET SDK and runtime images provide both ARM64 and x64 variants, Buildx can select the correct image during the build.
The application image then inherits the appropriate architecture.
Build for Both Platforms
With the Dockerfile in place:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t myregistry.example.com/myapp:latest \
--push .You can inspect the result:
docker buildx imagetools inspect \
myregistry.example.com/myapp:latestThe output should contain platform entries for both:
linux/amd64
linux/arm64Test Each Architecture
Building an image is not enough.
You should test the image on every supported architecture.
If you have an ARM64 development machine:
docker run --rm myregistry.example.com/myapp:latestDocker should select the ARM64 variant.
On an x64 machine, the same command should select the x64 variant.
You can also explicitly request a platform:
docker run \
--platform linux/amd64 \
--rm \
myregistry.example.com/myapp:latestAnd:
docker run \
--platform linux/arm64 \
--rm \
myregistry.example.com/myapp:latestThis is useful for testing from a machine that does not physically use the target architecture.
Emulation Is Useful, But It Is Not the Same as Native Testing
Docker can use emulation to build or run an image for another architecture.
For example, an ARM64 machine can build an x64 image through emulation.
This is convenient, but emulation has limitations.
Builds can be slower, and applications with architecture-specific native components may behave differently.
A good workflow is:
Local development
|
v
Build multi-platform image
|
v
CI validation
|
+---- ARM64 test
|
+---- AMD64 test
|
v
Registry
|
v
DeploymentFor important production workloads, native CI runners or native test environments can provide better confidence.
Native Dependencies Are the Difficult Part
Pure managed .NET code is generally easier to move between architectures.
The situation changes when the application depends on native libraries.
Examples include:
Database client libraries
Image processing libraries
Compression libraries
Cryptography libraries
Browser automation dependencies
System-level packages
Native Node.js modules
Custom C or C++ libraries
A package may work on x64 but not provide an ARM64 build.
For example:
Application
|
+---- Managed .NET code
|
+---- Native library
|
+---- x64 onlyThe ARM64 image can build successfully and still fail at runtime.
Watch Out for Architecture-Specific Package Installation
A Dockerfile may contain:
RUN apt-get update && \
apt-get install -y some-native-packageThat package needs to exist for the architecture being built.
With multi-platform builds, Docker executes the build for each target architecture.
Therefore:
linux/amd64 -> package for amd64
linux/arm64 -> package for arm64If the package is unavailable for ARM64, the ARM64 build can fail.
Do not assume that because a package exists in one architecture's repository, it exists in another.
Avoid Hard-Coded Architecture Paths
Some native tools install files into architecture-specific locations.
Code such as:
COPY native/x64/libexample.so /usr/lib/will obviously not work for an ARM64 image.
A multi-platform build should either:
Join the conversation! Your thoughts help the community grow.