Docker Mirror

A tool to mirror docker images

docker-mirror is a simple tool to mirror docker images between repositories, usually from the public docker hub to a local internal repository.

You would do this if you use an image frequently. For example I mirror the golang:alpine as I run a lot of builds using golang to compile multiple projects, so it makes sense to have a local mirror of that image.

This has multiple benefits:

  1. Builds are faster as any pull's occur locally removing the internet or your, usually slower than Ethernet internet connection.
  2. Docker now have limits on how often you can pull an image over a set period of time. If you have an image used across multiple machines this can quickly push you over the limit.
  3. If your internet connection goes down, or the public repository is unavailable you can still work


Because this utility uses the docker manifest command you need to enable experimental features to the Docker CLI.

You also need to be logged in to the destination repository when running the tool with an account that allows you to push to that repository.

Isn't this the same as docker pull?

In most instances you can do exactly the same thing with the following 3 docker commands:

1docker pull golang:alpine
2docker tag library/golang:alpine
3docker push

However this works only for images built for the same architecture as the machine running those commands.

If you have a muti-architecture environment, or need to support multiple architectures like amd64 & arm then this is where docker-mirror becomes useful as it will automatically mirror all architectures an image supports.

Doesn't docker already support a local mirror?

Yes it does, however it doesn't work due to a bug with docker #30880 causes it to fail for non-root users.

Where's the source?

The source for this tool is on github at

Mirroring an Image

How to mirror an image to a local docker repository

Using a mirrored image

How to use a mirrored image

Using docker-mirror in a Jenkins pipeline

How to use docker-mirror in a Jenkins pipeline

Last modified October 28, 2021: Use proper highlighting (42d84ca)