podman pull: Pull Images From a Registry
podman pull fetches an image (and its layers) from a container registry into local storage.
podman pull mirrors docker pull but is stricter about image names: unqualified short names can be rejected or prompt, so CI should always pull fully qualified references.
What it does
podman pull downloads the manifest and layers for an image reference from a registry into local storage. Unlike Docker, Podman resolves short names through registries.conf, which in enforcing mode requires a fully qualified name.
Common usage
podman pull docker.io/library/alpine:3.20
podman pull ghcr.io/owner/app:1.2.3
podman pull --platform linux/arm64 docker.io/library/node:20
podman pull --creds user:token registry.example.com/team/app:latestOptions
| Flag | What it does |
|---|---|
| --platform <os/arch> | Pull a specific platform variant |
| --creds <user:pass> | Supply registry credentials for this pull |
| --quiet | Suppress the per-layer progress output |
| --tls-verify=false | Skip TLS verification (insecure, test registries only) |
| --authfile <path> | Use a specific auth file instead of the default |
In CI
Always pull fully qualified references (docker.io/library/...) so the build does not depend on registries.conf search order or trip short-name enforcement. For private registries, podman login once and the cached credentials apply, or pass --authfile.
Common errors in CI
"Error: short-name resolution enforced ... no resolution found" means the name is unqualified and short-name-mode is enforcing; use docker.io/library/<image>. "unauthorized: authentication required" means you have not logged in or the token is wrong; run podman login first. "x509: certificate signed by unknown authority" on an internal registry needs the CA trusted or --tls-verify=false for test registries only.