Docker: The latest Confusion

One of the most misunderstood parts of Docker seems to be the latest tag. The confusion stems largely from its name, which doesn’t really reflect what the tag implies. In this post we’ll look at what the latest tag really does and what you should use it for.

There are two ways to tag images: using the docker tag command and passing the -t flag to docker build. In both cases, the argument is of the form repository_name:tag_name e.g. docker tag myrepo:mytag. If the repository is to be uploaded to the Docker Hub, the repository name must be prefixed with a slash and the Docker Hub user name e.g. amouat/myrepo:mytag. The trick is of course, if you leave the tag part out (e.g. _docker tag myrepo:1.0 myrepo), Docker will automatically give it the tag latest. You probably knew all this already, but it’s important to realise that this is about as far as it goes — the latest tag doesn’t have any magical powers.

Just because an image is tagged latest, does not mean that it is the most up-to-date image within its repository. It may be, but only if the repository owner has chosen to use this convention. I can easily push an old image to the latest tag e.g:

And you can see latest is now the same as the 0.9 image from two weeks ago, rather than the 1.0 image from a minute ago.

It’s easy to understand why this may surprise people — consider the sentence "just pull the latest image"; does this mean the image tagged latest, or the newest image in the repository? Are they the same thing? What does it even mean to be the newest image in a repo; is it the newest stable or the newest development image?

More worryingly, some people seem to believe that the latest tag will be automatically updated — that if I pull an image marked latest, docker will take care of checking it is still the newest version before running it each time. This is emphatically not the case – just as with every other tag, you still need to manually docker pull new versions.

The confusion doesn’t end there. What happens if I do a docker pull on a repository without specifying a tag? If you think you get all the images, you’re wrong – you just get the one tagged latest. You have to use the -a flag to get all the images. So what happens if you do the pull on a repository with no latest tag? This:

Unsurprisingly, you get an error message. But I bet you weren’t sure what was going to happen.

A further annoyance is the way the latest tag hides other tags. Suppose you download the latest tag for debian. Which version is it?

Err, no idea. Turns out it’s 7.8, aka wheezy:

I would rather Docker set all the tags for the image when it is downloaded, I’m not sure what the rationale is for not doing this. The current method means users can have different versions of images locally for tags that are identical on the server (e.g. if wheezy and latest are updated on the Hub and I pull debian:wheezy, my wheezy tag will be ahead of my latest tag even though they are identical on the Hub).

That just about covers most of the semantics of latest and how it is commonly misunderstood. So how could the situation be improved? Personally, I would like to see the latest tag deprecated and replaced with a name that more closely matches its semantics, such as "default". I would also like to see a few tweaks to the way tagging works, such as updating all the tags for an image at the same time. In the meantime however, I would strongly advise repository owners to be wary of the latest tag and consider not using it at all.

The following two tabs change content below.

Adrian Mouat

Adrian Mouat is Chief Scientist at Container Solutions and the author of the O'Reilly book "Using Docker". He has been a professional software developer for over 10 years, working on a wide range of projects from small webapps to large data mining platforms.

Latest posts by Adrian Mouat (see all)


  1. I’m on a project where everybody started using latest and then later had to implement versioning of images which turned out to be tricky because in dev you’d often like to use latest and elsewhere you need specific versions. This means that after each build you need to push two copies of the same image, one with :latest and one with :

    There are two options:

    1. Make latest a pointer
    2. Drop latest

    My preference would be for the latter. It might make the learning curve a little higher for noobs but it makes things very clear.

  2. This small issue with the “latest” tag can make things slightly unclear for newcomers to Docker. However, it becomes a very useful convention to follow when using the correct pull->build->tag->push process for building, and the stop->pull->start process for deployments.

    If you decide to implement the “:latest” tag convention, and you have a base image you are tracking “:latest” on, you should make sure you’re always pulling & building from the latest base image also. This becomes important when running builds on a Continuous Integration / Continuous Deployment server, as the “docker build” command will not explicitly pull the latest base image as well.

    The solution is to either explicitly run “docker pull base-image:latest” before running “docker build”, or simply use the “–pull” tag when building, as in: “docker build –pull -t my-image:v1.2.3 . “

    • I don’t understand what that has to do with the latest tag. For instance, if you’re using redis:3 as a base image, it would be best practice to pull redis:3 before building to make sure it is up-to-date.

  3. What’s the tldr; takeaway here? All I get is because of some social dysfunction “latest” is a proliferating ball of confusion that should be avoided like a ravine full of venomous snakes…

    • Yeah, I’m just saying if you use the latest tag, be sure you know what it means. If you have a repo, you might want to consider tags such as “master” for the version built from the latest github check-in and “stable” for the latest stable version.

Leave a Reply

Your email address will not be published. Required fields are marked *