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:
# Creates my-image:latest (first image) docker build -t my-image # Updates my-image:latest (second image) docker build -t my-image:latest # Creates my-image:v1 (third image) docker build -t my-image:v1
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: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
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
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
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.
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.