Sometimes it seems that there are few misconceptions about Docker tags. Below, I’ll try to clear things up with couple of examples.
In short, tags for images are not mandatory, but highly recommended. If you give an image a name but not a tag, it will be automatically tagged as “latest”. This does not necessarily mean that the image is the latest version or build. The tag “latest” is more of a convenience feature, which is used when you call a Docker command that expects a tag but you don’t provide one.
As an example, Debian Linux distribution:
In the picture, each line represents a Docker image. The tag “latest” is assigned to the bullseye version, which is also a version 11. The list also has an image called bookworm, which will have a version 12 sometimes in the future. If a user runs a command docker run debian
or docker run debian:latest
, the user will not receive the latest and greatest cutting-edge version (bookworm or 12) but the latest officially released stable version 11 (i.e bullseye).
Neither a name or a tag are mandatory. By calling command docker build .
, the resulting build will be nameless and tag-less:
REPOSITORY TAG IMAGE ID CREATED SIZE <none> <none> 6b6da5366a5e 26 seconds ago 752MB
Docker will name all images with IMAGE ID. The ID looks like this: “6b6da5366a5e” and it is unique to each image. In other words, if you don’t name an image, you always can refer to it by using the ID.
When you give a name, you can leave a tag out. Docker will then automatically use the tag “latest”. For example docker build -t testimage .
:
REPOSITORY TAG IMAGE ID CREATED SIZE testimage latest 6b6da5366a5e 5 minutes ago 752MB
With tags you can give a descriptive names to the image. Also, with tags you can tell about versions.
If you give a tag, no “latest” tag is used. For example, docker build -t testimage:v1 .
:
REPOSITORY TAG IMAGE ID CREATED SIZE testimage v1 6b6da5366a5e 14 minutes ago 752MB
This is one reason why you should not count on the idea that the “latest” tag always points to the latest build or version.
You can also add and remove tags. By running the command docker tag --help
we will get short instructions:
Usage: docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
These instructions, while not the clearest possible, will tell us that a tag is actually a combination of an image name and an optional additional definition, be it a version number or an alias or something else. Also, the tag is just a reference to the actual image file.
You can add a tag by using the command docker tag testimage:v1 testimage:firstversion
:
REPOSITORY TAG IMAGE ID CREATED SIZE testimage firstversion 6b6da5366a5e 31 minutes ago 752MB testimage v1 6b6da5366a5e 31 minutes ago 752MB
Removing a tag looks scary, docker image rm testimage:firstversion
:
Untagged: testimage:firstversion
Despite of the scary-looking command, Docker actually does not delete the image file but simply removes the tag, if there are multiple tags pointing to the image file. If you run the command to an image that only has one tag, Docker will delete the whole image file. This is because of the Docker architecture behind the scenes.
I hope that these examples clarified a bit how Docker tags behave. You can read additional information from here: Docker Reference: docker tag
Writer is Matti Kärki, a senior developer from Ouro