A registry configuration file declares the registries Podman uses to resolve container image references. Podman relies on the containers/image library for image transfers, while registries.conf primarily controls registry access, short-name resolution, and mirrors. section 5.2 section 5.5
The system-wide file is /etc/containers/registries.conf; a user-specific $HOME/.config/containers/registries.conf takes precedence when present. In remote mode, edit the file on the Linux server, or use podman machine ssh with a Podman machine. section 5.2.1
Configure registry resolution and access through these mechanisms:
- Set unqualified-search-registries to an ordered array of host[:port] registries tried for short image names. section 5.2.1
- Use fully qualified image names when registry identity matters; short-name prompts and recorded mappings reduce ambiguity but do not replace explicit references. section 2.2.8
Change the search registries
Back up /etc/containers/registries.conf, replace docker.io with example.com in unqualified-search-registries, and run podman info to verify the resulting search order. Pulling an unknown short name can then display candidates from the configured registries.
Block a registry
A [[registry]] entry with Location = "docker.io" and blocked=true prevents matching pulls. podman info reports the blocked setting, and podman pull docker.io/ubuntu fails with a registry-blocked error.
