Ambiguous Podman Multi-Arch Build Output: Silent Single-Arch Image Creation

[kaovilai]

Feature request description

When migrating from Docker to Podman, the multi-arch build workflow has several differences that create friction for users familiar with Docker's approach. While these are not functional blockers, they significantly impact ease of use and require rewriting existing build scripts.

Current Docker workflow:

# Single command builds all platforms into a multi-arch image
docker buildx build --platform linux/amd64,linux/arm64 -t myimage:tag .

# Push works as expected
docker push myimage:tag

Current Podman workflow:

# Comma-separated platforms work, but require --manifest flag to create multi-arch image
# Using -t with multiple platforms only produces single arch image
podman build --platform linux/amd64,linux/arm64 --manifest myimage .

# Must use 'manifest push' subcommand instead of regular push
# Regular 'podman push' only pushes single arch
podman manifest push myimage docker://registry/myimage:tag

Issues:

1. Must use --manifest flag for multi-arch: While comma-separated --platform values work, using -t/--tag with multiple platforms only produces a single architecture image. You must use --manifest flag to create a multi-arch manifest.
2. Different push command: Must use podman manifest push instead of podman push. Regular podman push only pushes single arch even if the local image is a manifest.

Impact:

• Existing Dockerfiles and CI/CD scripts need modification
• Mental model shift required for users familiar with Docker
• Cannot use same -t/--tag pattern for both single-arch and multi-arch builds
• Documentation and training materials need updates
• Harder to switch between Docker and Podman in mixed environments

Suggest potential solution

Consider adding Docker CLI compatibility mode for multi-arch builds:

1. When -t/--tag is used with comma-separated --platform values, automatically create a manifest (instead of single arch)
2. Make podman push detect if the image is a manifest and automatically use manifest push logic

Example improved workflow:

# Works like Docker - automatically creates manifest when multiple platforms specified
podman build --platform linux/amd64,linux/arm64 -t myimage:tag .

# Push automatically detects manifest and pushes multi-arch
podman push myimage:tag

This would maintain backward compatibility with the current --manifest workflow while providing a more familiar interface for Docker users.

Have you considered any alternatives?

Alternative approaches:

1. Keep current workflow but improve documentation highlighting the differences and providing migration guides
2. Add a compatibility flag like --docker-compat that enables Docker-like behavior
3. Make -t an alias for --manifest when multiple platforms are specified

However, these don't fully address the friction point of having to remember different commands for single-arch vs multi-arch workflows.

Additional context

Environment:

Client:        Podman Engine
Version:       5.6.0
API Version:   5.6.0
Go Version:    go1.25.0
Git Commit:    da671ef6cfa3fc9ac6225c18f1dd0a70a951e43f
Built:         Fri Aug 15 11:42:23 2025
Build Origin:  pkginstaller
OS/Arch:       darwin/arm64

Server:       Podman Engine
Version:      5.5.2
API Version:  5.5.2
Go Version:   go1.23.10
Git Commit:   e7d8226745ba07a64b7176a7f128e4ef53225a0e
Built:        Mon Jun 23 20:00:00 2025
OS/Arch:      linux/arm64

Related issues:

• Building multi-arch with podman appears to result in a pushed image with only one arch #13676 - Building multi-arch with podman
• Accept --arch based on uname -m names (ie x86_64/aarch64) in addition to GOARCH like arch (ie amd64/arm64) #12680 - Accept --arch based on uname -m names
• Podman manifest create for image list/index produces docker v2s2 format only #21294 - Podman manifest create format concerns

This is primarily an ease-of-use and migration concern, not a functional limitation. The functionality exists, but the UX differs from Docker in ways that create unnecessary friction for users migrating their workflows.

[Honny1]

This seems like a good candidate for Podman 6.0. WDYT? @baude

[baude]

I think others more specialized in building images will need to speak up here. I hate the notion of chasing Docker CLI for these kinds of things because it is an endless chase. And that is the fundamental problem I have with this kind of request; it's not make ease of use better, it is make it more like Docker. Sometimes that's valid. Let's see what the gang says.

I do agree the manifests/images thing is kind of confusing and can confuse those coming from docker. on the other hand, many of our users are quite comfy with the approach. hopefully some compromise can be driven.

[kaovilai]

kinds of things because it is an endless chase.

agree.

What I don't get is why podman build --platform linux/amd64,linux/arm64 -t myimage:tag . doesn't fail, and produces undesired single arch.

Producing misleading results with no errors silently is what I am against.

[kaovilai]

Either join em, make it work as expected, or nudge another command.

[kaovilai]

There is zero scenario where
podman build --platform linux/amd64,linux/arm64 -t myimage:tag .

should produce a resulting tag as a single arch image.

[kaovilai]

podman build --platform linux/amd64,linux/arm64 -t myimage:tag . && podman push myimage:tag
podman build --platform linux/amd64,linux/arm64 --manifest myimage:tag . && podman push myimage:tag

should result in multiarch image being pushed, not single arch. That seems to not be the case last I reproduce.

[kaovilai]

I hate the notion of chasing Docker CLI for these kinds of things

because podman is often advertised as a drop in.

and for the compatibility layer where you could use the actual docker cli, we still have remaining open issues.
#24000

I have opened a PR in moby/buildkit on this btw to no avail.

[kaovilai]

Retitled to get at the meat of the issue, which is the confusing results the podman cli currently produces, which if can be solved in a way that make it work like docker cli, great.. being different for sake of different is also ok if it make sense.

Currently it does not make sense.