# podman pull: Pull Images From a Registry

> podman pull downloads an image from a registry. Reference for fully qualified names, --platform, --creds, and the short-name and auth errors in CI.

Source: https://latchkey.dev/learn/command-reference/podman-pull  
Updated: 2026-06-30

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

```Terminal
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:latest
```

## Options

| 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.

## FAQ

### podman pull: Pull Images From a Registry?

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.

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt