Docker 101: image tags

Dec 02, 2022 · 2 mins read · Post a comment

Tagging Docker images helps by providing a distinctive identity to the image itself by adding certain metadata in the following format: <docker_username>/<image_name>:<tag>. This stands for Docker registry only. However, if you are dealing with for example an AWS container registry (ECR) or Azure’s equivalent (ACR) you’ll have something different from the <docker_username> part. For instance: <some_id><image_name>:<tag>, <some_id><namespace>/<image_name>:<tag>. To keep things simple, I’ll stick to the Docker registry.

<docker_username> and <username> are used interchangeably.


  • Docker


build and tag a Docker image

docker build -t <username>/<image_name>:<tag> .

Example: docker build -t devcoops/mywebapp:1.2 .


  • If you don’t specify any tag, and just run: docker build -t devcoops ., Docker will automatically assign the well known latest tag.
  • If you omit even the username: docker build . , you’ll get the following image name and tag: <none>:<none>. So, you’ll have no choice except to reference the image by the IMAGE ID.

update tag

To update a Docker image tag, run:

docker tag <username>/<old_image_name>:<tag> <username>/<new_image_name>:<tag>

Example: docker tag devcoops/mywebapp:1.2 devcoops/api:1.2

multiple tags

Not very often, multiple tags are required depending on the Docker image tag strategy. To achieve this, take a look at the following examples:

Build and add multiple tag:

docker build -t <username>/<image_name>:<tag_1> -t <username>/<image_name>:<tag_2>

Example: docker build -t devcoops/api:1.2 -t devcoops/api:prod

Update Docker image tag to have multiple tags:

docker tag <username>/<image_name>:<tag> <username>/<image_name>:<new_tag_1>
docker tag <username>/<image_name>:<tag> <username>/<image_name>:<new_tag_2>


  • docker tag devcoops/api:latest devcoops/api:1.2
  • docker tag devcoops/api:latest devcoops/api:prod

remove tag

Finally, to get rid of a tag, just remove the image lol:

docker rmi <username>/<image_name>:<tag>

Example: docker rmi devcoops/api:latest


Related post: Docker Registry vs Docker Repository.

Feel free to leave a comment below and if you find this tutorial useful, follow our official channel on Telegram.