Docker tags are used to identify images by name. Each image can have multiple tags assigned. Tags look similar to my-image:latest, with the part before the colon defining the image name and the latter section specifying the version.
You can tag an image without anything after the colon. Your image will be automatically given latest as its version tag. This is a common source of confusion for newcomers to Docker.
The Problems With latest
The semantics of the latest tag seem to suggest some special meaning beyond what actually exists. In reality, latest is used as the default tag when you haven’t specified anything else. That’s the only time it’ll be used – it doesn’t automatically refer to the newest image you’ve built.
Here’s an example of the resulting problem:
If you now ran docker run my-image:latest, you’d be using the second image to be built. The v1 tag is completely independent of latest, so building the third image has no effect on the existing two. If you wanted my-image:v1 to also become the latest image, you’d need to manually tag and push it in a separate operation.
This creates a lot of confusion within the Docker ecosystem. Many image creators do tag their newest releases with latest. This imbues the tag with extra importance that Docker didn’t intend. Other authors use latest for their development builds, while some won’t publish a latest tag at all.
The lack of consistency among image authors can make it unclear whether latest is really the latest image or not. The most important rule of latest is to never make assumptions about how a particular image will use the tag.
Avoid Pinning to latest
You shouldn’t consume the latest tag of an image whenever a more specific alternative is available. Unless you know the image’s author actively updates the latest tag, pinning against it might not deliver the version you expect.
Most images use semantic versioning to create release tags. It’s much safer to consume my-image:1.1 than my-image:latest. If the author doesn’t maintain latest, you could end up with a heavily outdated image. Conversely, authors that do maintain latest often use the tag for their bleeding-edge development version. Pinning against it is likely to deliver regular breaking changes that you won’t be warned about.
Several container ecosystem projects now warn against using latest for this reason. Kubernetes notes that using latest is not only unpredictable but also makes it harder for you to identify the real image version used by your containers.
Rolling back a container that’s deployed with latest isn’t directly possible. You’ve got no reference point to work with. Changing an image tag from 1.1.0 to 2.1.0 lets you easily revert the upgrade if you need to. Container orchestration tools can’t help you change “the new latest image” back into “the old latest image”.
Immutability
More fundamentally, good tagging practice dictates that image tags should be immutable. Once a tag’s been assigned, that tag shouldn’t be reused by the same image. This allows downstream consumers to pin against specific versions, safe in the knowledge they’ll get the same image each time.
latest breaks this system by being inherently mutable. If you use latest, you have to accept change. As an image author, you’ll make it more difficult for users to confidently reference your image if you only publish with the latest tag.
Many tools make assumptions about how image tags are used. latest often gets special treatment which you need to stay aware of. Kubernetes, for example, will always try to pull a newer version of the latest tag, even if one already exists locally. Other tags only get pulled if they don’t already exist within the cluster.
Better Approaches to Tagging
Try to stick to semantic versioning when you’re tagging images that will be publicly available. This is a widely understood standard that helps communicate the magnitude of each change you make to your image.
You have more options when creating images for private use. Images which are built by a CI server can often be tagged with the SHA of the commit which ran the pipeline. This ensures each pipeline creates a unique tag that won’t be overwritten in the future. It also helps you match images in your container registry to the codebase changes that created them.
Finally, don’t overthink the latest tag. You don’t need to keep it updated with the “latest” version of your image. It’s often best to ignore it altogether – unless you run docker build without a tag name, it’ll never be created. If you do publish a latest tag, make sure you state what it will refer to.
Summary
The apparent simplicity of Docker’s latest tag masks a quagmire of possible issues. You’ll encounter them both as an image author and consumer. The problems stem from the semantic inconsistency of the tag: while it sounds dynamic, it’s nothing more than a static tag assigned by Docker in the absence of a user-supplied value.
You should pin against specific image versions wherever possible. This will help you avoid breaking changes and ambiguous third-party tool behaviours. As an image author, try to provide semantic release versions and make it clear how your project treats latest. This will help prospective users assess how to reference your image.
