Podman resolves unqualified image names by consulting the registry list defined in unqualified-search-registries. To optimize download performance within mainland China, configure domestic mirror endpoints via the registries.conf file.

Configuration files follow a hierarchy:

• System-wide: /etc/containers/registries.conf
• Per-user: $HOME/.config/containers/registries.conf

When using Podman Machine (macOS/Windows), SSH into the Linux VM before modifying system-level settings:

podman machine ssh
cp /etc/containers/registries.conf ~/registries.conf.backup.$(date +%s)

Available Docker Hub mirrors for Chinese networks include:

Provider	Endpoint
Alibaba Cloud	https://<your-id>.mirror.aliyuncs.com (requires account)
Baidu	https://mirror.baidubce.com
NetEase	http://hub-mirror.c.163.com
Shanghai Jiao Tong University	https://docker.mirrors.sjtug.sjtu.edu.cn
Nanjing University	https://docker.nju.edu.cn

Edit the configuration to define the primary registry and fallback mirrors:

unqualified-search-registries = ["docker.io"]

[[registry]]
prefix = "docker.io"
location = "docker.nju.edu.cn"
insecure = true

[[registry.mirror]]
location = "mirror.baidubce.com"
insecure = true

[[registry.mirror]]
location = "hub-mirror.c.163.com"
insecure = true

[[registry.mirror]]
location = "docker.mirrors.sjtug.sjtu.edu.cn"
insecure = true

Configuration semantics:

• prefix: The repository namespace that triggers this rule (e.g., docker.io matches nginx:latest).
• location: The actual endpoint queried for image layers.
• insecure: Allows HTTP-only connections, necessary for certain mirrors or enternal registries without TLS certificates.

Apply the configuration non-interactively using a backup script:

#!/usr/bin/env bash

TARGET="/etc/containers/registries.conf"
ARCHIVE_DIR="/var/tmp/registries-backup"
STAMP=$(date +%Y%m%d-%H%M%S)

[[ -d "$ARCHIVE_DIR" ]] || sudo mkdir -p "$ARCHIVE_DIR"
[[ -f "$TARGET" ]] && sudo cp "$TARGET" "$ARCHIVE_DIR/registries.conf.$STAMP"

sudo tee "$TARGET" > /dev/null <<'REGCONFIG'
unqualified-search-registries = ["docker.io"]

[[registry]]
prefix = "docker.io"
location = "mirror.baidubce.com"
insecure = true

[[registry.mirror]]
location = "docker.nju.edu.cn"

[[registry.mirror]]
location = "hub-mirror.c.163.com"

[[registry.mirror]]
location = "docker.mirrors.sjtug.sjtu.edu.cn"
REGCONFIG

Validate that Podman recognizes the new registries:

podman info --format '{{ range .Registries }}{{ .Name }}: {{ .URL }}{{ printf "\n" }}{{ end }}'

Test the mirror chain by pulling an image without a fully qualified reference:

podman pull alpine:latest

Podman attempts the primary location first, then iterates through [[registry.mirror]] entries upon timeout or failure, before finally falling back to the original upstream endpoint.