4.2.1.3 FROM Platform Target

A FROM platform target specifies which CPU architecture and operating system a particular build stage should target, which matters when building images intended to run on a different platform than the machine performing the build, or when producing a single image that supports multiple platforms.

Specifying a Target Platform Explicitly

The --platform flag, or a platform argument within the Dockerfile itself, tells the build process which architecture to target, overriding whatever the build machine's own native architecture happens to be.

FROM --platform=linux/amd64 python:3.12-slim

This ensures the build targets the amd64 architecture specifically, even if the build is actually running on a different architecture, such as Apple Silicon's arm64.

Why Platform Targeting Matters for Cross-Building

Building on a developer's local machine and deploying to cloud infrastructure with a different CPU architecture is increasingly common, making explicit platform targeting necessary to avoid producing an image that fails to run once deployed.

docker buildx build --platform linux/amd64 -t myapp:1.0 .

Building Multi-Platform Images

Using buildx, a single build invocation can produce and publish images for multiple platforms simultaneously, with the registry automatically serving the correct variant to each pulling host based on its own architecture.

docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/myapp:1.0 --push .

A host pulling this tag automatically receives the variant matching its own architecture, without needing to specify anything platform-specific itself.

Verifying an Image's Target Platform

The platform an already-built image targets can be inspected directly, which is useful for confirming an image will actually run correctly on its intended deployment target before attempting to deploy it.

docker inspect myapp:1.0 --format '{{.Architecture}}'

Why Platform Targeting Matters

As development increasingly happens on a variety of machine architectures while production infrastructure often targets a specific, different architecture, explicitly specifying and verifying platform targets has become an essential step in avoiding deployment failures caused by an architecture mismatch.