Container Regisrty Configuration in Podman
Podman operates without a daemon, which means it interacts directly with the Linux kernel through runc. This architectural difference from Docker has practical implications for how you manage container registries.
Default Registry Configuration
When you install Podman, it comes pre-configured with four container registries. You can view and modify the registry configuration through the Podman Desktop GUI under Settings → Registries, or by directly editing the configuration files.
The default registries are:
- Docker Hub —
https://docker.io - Red Hat Quay —
https://quay.io - GitHub Container Registry —
https://ghcr.io - Google Container Registry —
https://gcr.io
Configuration files are located at:
- System-wide:
/etc/containers/registries.conf - Per-user:
~/.config/containers/registries.conf
Why Configure Mirror Registries?
Pulling images directly from upstream registries can be slow or unreliable due to network latency. Mirror registries act as caching proxies, significantly improving pull speeds for users in certain regions.
Available Mirror Registries
Several mirror registries are publicly accessibel:
| Provider | Address |
|---|---|
| NetEase | http://hub-mirror.c.163.com |
| Baidu | https://mirror.baidubce.com |
| Shanghai Jiao Tong University | https://docker.mirrors.sjtug.sjtu.edu.cn |
| Nanjing University | https://docker.nju.edu.cn |
| Alibaba (requires login) | http://<your-id>.mirror.aliyuncs.com |
Note: The former Docker CN mirror (
https://registry.docker-cn.com) is no longer available.
Modifying the Registry Configuration
The configuration file registries.conf uses a TOML-based format. Follow these steps to update it:
- Access the Podman machine virtual machine:
podman machine ssh [machine-name]
- Back up the existing configuration:
sudo cp /etc/containers/registries.conf /etc/containers/registries.conf.backup
- Inspect the current file:
sudo cat /etc/containers/registries.conf
The default configuration typically looks like this:
unqualified-search-registries = ["docker.io"]
[[registry]]
prefix = "docker.io"
location = "docker.io"
- Open the file for editing:
sudo vim /etc/containers/registries.conf
Apply the following configuration to set up multiple mirrors:
unqualified-search-registries = ["docker.io"]
[[registry]]
prefix = "docker.io"
location = "hub-mirror.c.163.com"
insecure = true
[[registry.mirror]]
location = "mirror.baidubce.com"
insecure = true
[[registry.mirror]]
location = "docker.mirrors.sjtug.sjtu.edu.cn"
insecure = true
[[registry.mirror]]
location = "docker.nju.edu.cn"
insecure = true
Configuration Directives Explained
| Directive | Purpose |
|---|---|
unqualified-search-registries |
Specifies which registries to search when no full registry URL is provided |
prefix |
The namespace prefix used when pulling images (defaults to location if unset) |
location |
The actual registry endpoint to pull from |
insecure = true |
Allows HTTP connections (useful for internal/private deployments without TLS certificates) |
[[registry.mirror]] |
Defines fallback mirror registries, tried in order if the primary location fails |
Automated Configuration Script
For a reproducible setup, use this shell script:
#!/bin/bash
BACKUP_DIR="/etc/containers/registries.conf.bak"
[ -d "$BACKUP_DIR" ] || sudo mkdir -p "$BACKUP_DIR"
sudo cp /etc/containers/registries.conf "$BACKUP_DIR/registries.conf.$(date +%Y%m%d%H%M%S).bak"
sudo tee /etc/containers/registries.conf > /dev/null << 'EOF'
unqualified-search-registries = ["docker.io"]
[[registry]]
prefix = "docker.io"
location = "hub-mirror.c.163.com"
insecure = true
[[registry.mirror]]
location = "mirror.baidubce.com"
insecure = true
[[registry.mirror]]
location = "docker.mirrors.sjtug.sjtu.edu.cn"
insecure = true
[[registry.mirror]]
location = "docker.nju.edu.cn"
insecure = true
EOF
echo "Registry configuration updated successfully."
Verifying the Configuration
After modifying the configuration, restart the Podman machine to apply changes:
podman machine stop
podman machine start
Test the setup by pulling a public image:
podman pull nginx
If you encounter issues, verify the configuration syntax and ensure the Podman machine is using the updated file.