Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

CircleCI Go Report Card License Github downloads GitHub release

Docker Retag

🐳 Retag an existing Docker image without the overhead of pulling and pushing


There are certain situation where it is desirable to give an existing Docker image an additional tag. This is usually acomplished by a docker pull, followed by a docker tag and a docker push.

That approach has the downside of downloading the contents of every layer from Docker Hub, which has bandwidth and performance implications, especially in a CI environment.

This tool uses the Docker Hub API to pull and push only a tiny manifest of the layers, bypassing the download overhead. Using this approach, an image of any size can be retagged in approximately 2 seconds.


From source

You can use go get to install this tool by running:

$ go get -u

Precompiled binary

Alternatively, you can download a static Linux release binary by running:

$ wget -q
$ sudo install docker-retag /usr/bin



Since docker-retag communicates with the Docker Hub API, you must first export your account credentials into the working environment. These are the same credentials that you would use during docker login.

$ export DOCKER_USER='joshdk'
$ export DOCKER_PASS='hunter2'

The credentials must have both pull and push access for the Docker repository you are retagging.


This tool can be used in a few simple ways. The simplest of which is using a source image reference (similar to anything you could pass to docker tag) and a target tag.

Referencing a source image by tag name.
$ docker-retag joshdk/hello-world:1.0.0 1.0.1
  Retagged joshdk/hello-world:1.0.0 as joshdk/hello-world:1.0.1
Referencing a source image by sha256 digest.
$ docker-retag joshdk/hello-world@sha256:933f...3e90 1.0.1
  Retagged joshdk/hello-world@sha256:933f...3e90 as joshdk/hello-world:1.0.1
Referencing an image only by name will default to using latest.
$ docker-retag joshdk/hello-world 1.0.1
  Retagged joshdk/hello-world:latest as joshdk/hello-world:1.0.1

Additionally, you can pass the image name, source reference, and target tag as seperate arguments.

$ docker-retag joshdk/hello-world 1.0.0 1.0.1
  Retagged joshdk/hello-world:1.0.0 as joshdk/hello-world:1.0.1
$ docker-retag joshdk/hello-world @sha256:933f...3e90 1.0.1
  Retagged joshdk/hello-world@sha256:933f...3e90 as joshdk/hello-world:1.0.1

In all cases, the image and source reference must already exist in Docker Hub.


This library is distributed under the MIT License, see LICENSE.txt for more information.