Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Containers and Images

Pulling and Searching Images: Registries and Short Names

Understand image names, tags and digests, pull and search registries, configure registries.conf and short-name resolution, and log in to private registries.

Every container starts from an image, and every image has a name that tells Podman where to get it. Getting names right is a surprisingly big part of using Podman well, because one of its deliberate differences is that it refuses to guess which registry you mean. This lesson explains how image names are built, how to search and pull, how short names are resolved, and how to authenticate to a private registry.

Anatomy of an image name

A fully qualified reference has up to four parts:

TEXT
registry.example.com:5000 / team/app : 1.4.2   @sha256:3f1c...
|------ registry --------|  |-path-|  |tag|    |---digest---|
  • Registry: the server, with an optional port. Docker Hub is docker.io; Quay is quay.io; GitHub's is ghcr.io.
  • Repository path: namespace and name. Official Docker Hub images live in the library namespace: docker.io/library/nginx.
  • Tag: a movable label such as 1.27, alpine or latest. If you omit it, the tag is latest.
  • Digest: an unchangeable content hash. nginx@sha256:... always means exactly the same bytes.

A tag can move: nginx:alpine today may be a different image next month. A digest never moves, so it is the right choice for reproducible deployments. A common pattern is to pin a version tag in development and the digest in production.

Here is a stand-in parser for image references. It is JavaScript written for this lesson, and it follows the rules above (the first part is a registry only if it contains a dot, a colon or is localhost).

JS Stand-in: parse an image reference

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Pulling images

Terminal
podman pull docker.io/library/alpine:3.20
podman pull quay.io/podman/hello
podman pull --platform linux/arm64 docker.io/library/alpine:3.20
podman images

podman images lists repository, tag, ID, created time and size. A pull downloads only layers you do not already have. --platform fetches an image for a different CPU architecture than your own, which is useful for building multi-architecture images, but such an image can run only through emulation.

podman run pulls automatically when the image is missing. Use --pull=always to check the registry every time, or --pull=newer to pull only if the registry has a newer one.

Searching

Terminal
podman search nginx
podman search --limit 5 docker.io/library/nginx
podman search --filter is-official=true nginx
podman search --list-tags docker.io/library/nginx --limit 10

Search asks registries that support it (Docker Hub and Quay do; many private registries do not). Results show the name, description and stars. Treat search as discovery only. Always check who publishes an image before you run it: prefer official images and verified publishers, and read the image's page for how it is built.

Short names

If you type podman pull nginx, nginx is a short name: it has no registry. Podman must decide where to look, and it does not silently assume Docker Hub. It uses these rules, in order:

  1. Aliases from [aliases] in registries.conf (and files under registries.conf.d). Many common names are mapped: for example, nginx might be defined as docker.io/library/nginx, depending on your distribution's alias list.
  2. Unqualified search registries, a list in unqualified-search-registries, tried in order.
  3. A mode that says what to do when the name is ambiguous: short-name-mode.
Mode Behavior
enforcing (the default on most installs) ask you which registry on a terminal; fail if there is no terminal and more than one matches
permissive like enforcing, but without a terminal it tries the registries in order
disabled try all search registries in order, no questions asked (not recommended)

When Podman asks, it records your answer in ~/.cache/containers/short-name-aliases.conf, so it asks only once per name.

The reason is security: an attacker could publish an image with a popular name on a registry that is searched first. Using a fully qualified name avoids the whole problem, so always write the registry in scripts, Containerfiles and Compose files.

registries.conf

The file is TOML and lives at /etc/containers/registries.conf (system) or ~/.config/containers/registries.conf (user), plus drop-ins in registries.conf.d/:

TOML
unqualified-search-registries = ["docker.io", "quay.io"]
short-name-mode = "enforcing"

[aliases]
"myapp" = "registry.example.com/team/myapp"

[[registry]]
location = "docker.io"
[[registry.mirror]]
location = "mirror.example.com/dockerhub"

[[registry]]
location = "registry.internal:5000"
insecure = true     # plain HTTP or unverified TLS: only for a private lab
  • aliases map short names to full ones, which teams use to make podman run myapp safe.
  • mirrors let Podman try another location first; they are used to cut bandwidth or to work in networks that cannot reach the public internet.
  • insecure disables TLS verification for one registry. Avoid it outside a throwaway lab. Per-command, --tls-verify=false does the same.

Here is a stand-in that mimics the short-name decision. It is a simplified model written for this course.

JS Stand-in: short-name resolution

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Private registries and authentication

Terminal
podman login registry.example.com
podman login --username alice --password-stdin ghcr.io < token.txt
podman logout registry.example.com

Login stores credentials in an auth file: $XDG_RUNTIME_DIR/containers/auth.json (cleared on logout of the session) by default, or a persistent file if you set REGISTRY_AUTH_FILE. It can also use a credential helper. Never put passwords on the command line; read tokens with --password-stdin. For automation (CI), use a token with the narrowest rights.

Check an image without pulling it fully, using Skopeo:

Terminal
skopeo inspect docker://docker.io/library/alpine:3.20

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which part of an image reference never changes its content?

    A digest is a content hash. A tag can be moved to a different image at any time.
  2. 2. Why does Podman not silently assume Docker Hub for short names?

    Resolution follows aliases and search registries, and in enforcing mode ambiguity becomes a prompt or an error.
  3. 3. What is the best practice for image names in a Containerfile or script?

    Fully qualified names remove ambiguity and work the same on every machine.
  4. 4. Where is the user-level registries configuration?

    System settings are in /etc/containers, and rootless users can override them in ~/.config/containers.
  5. 5. How should you pass a registry token during podman login in a script?

    --password-stdin keeps the secret out of the process list and shell history.

Summary

  • An image reference has registry, repository path, tag and optional digest; digests are immutable.
  • podman pull, podman images and podman search get and discover images; always check the publisher.
  • Short names are resolved by aliases, then search registries, under short-name-mode.
  • Write fully qualified names in anything you share.
  • registries.conf configures aliases, search order, mirrors and insecure registries.
  • Use podman login --password-stdin and narrow-scope tokens for private registries.

Next: Image Storage, Layers and Tags