Get rid of Docker Hub limits with Podman

If you don’t have a paid subscription, you are probably aware that Docker Hub has some limitations on its usage that may cause errors in your daily developer workflow. These limits are documented there

So if you reached that state, you should have seen a response like the following:

$ podman pull docker.io/library/nginx
Trying to pull docker.io/library/nginx:latest...
Error: initializing source docker://nginx:latest: reading manifest latest in docker.io/library/nginx: toomanyrequests: You have reached your unauthenticated pull rate limit. https://www.docker.com/increase-rate-limit

Once you’ve reached that state, the only action you can take is to wait for some time as the limits on Docker Hub are computed per hour.

We will show you can benefit from a Podman feature and get rid of this limitation in a very simple manner

Podman registries management

Podman has 2 features regarding registries that we can benefit from to get rid of this limitation:

• you can declare mirrors for a registry so that they will be use if the main registry does not respond or does not have the required image.

• you can override the destination for a specific prefix

The first one is not very helpful as Docker Hub increase a lot the response time (over a minute) once the limit has been reached.

The second one is the one we should use as it would just require to associate the docker.io prefix to a Docker Hub mirror.

So now the question is: where is there a maintained Docker Hub mirror. And the answer is mirror.gcr.io which is hosted on the Google Cloud Platform (GCP) and maintained by Google.

Podman has a lot of different places where you can configure the registries: the one from the distribution (which users are not supposed to modify), a system wide one and a user specific one. As Podman machines can be switched from rootless to rootful, we will modify the system wide configuration so that it applies to all configurations.

System wide, the registries configuration files are stored in /etc/containers/registries.conf.d. By default, this folder has 2 files named 000-shortnames.conf and 999-podman-machine.conf.

The following section should be added to one of these files (please note that we can also add a new file in this repository):

[[registry]]
prefix="docker.io"
location="mirror.gcr.io"

So in order to update the file, execute the following commands:

podman machine ssh
sudo cat <<EOF >/etc/containers/registries.conf.d/999-podman-machine.conf
[[registry]]
prefix="docker.io"
location="mirror.gcr.io"
EOF
exit

Your Podman machine is now properly configured and you should not be subject to Docker Hub limitations anymore

To be continued

As we found a nice solution to get rid of the Docker Hub limitations, it has the disadvantage of being repeated each time a Podman machine is started. So, in a next article, we will develop a Podman Desktop extension that will perform automatically the configuration on the available Podman machines. Stay tuned…