Tag an Image With a Version and latest

You built an image and it is called shop-app, which really means shop-app:latest. You cannot tell which version that is, and you cannot go back to the one before. Tag every build with its version, and keep latest only as a convenience. This page is the short version of the lesson on tagging.

Tag while you build

-t can be repeated. One build, several names, one image.

shop 1.2.0

FROM alpine:3.24
COPY version.txt /version.txt
CMD ["cat", "/version.txt"]

Set-Location tagver-demo
$version = "1.2.0"
docker build -q -t "shop-app:$version" -t shop-app:latest . | Out-Null
docker image ls shop-app --format "table {{.Repository}}\t{{.Tag}}" | Sort-Object
"distinct images: " + @(docker image ls shop-app --format "{{.ID}}" | Sort-Object -Unique).Count

REPOSITORY   TAG
shop-app     1.2.0
shop-app     latest
distinct images: 1

Two tags, one image, so latest costs nothing. Keep the version in one variable, here $version, and use it everywhere: the tag, the file and your notes.

Tag an image you already built

docker tag SOURCE TARGET adds a name to an existing image. It does not copy it. Add the short Git commit, so you can trace any running container to its code. The commit here is made up.

docker tag shop-app:1.2.0 shop-app:1.2
docker tag shop-app:1.2.0 shop-app:commit-a1b2c3d
docker image ls shop-app --format "{{.Tag}}" | Sort-Object
"distinct images: " + @(docker image ls shop-app --format "{{.ID}}" | Sort-Object -Unique).Count

1.2
1.2.0
commit-a1b2c3d
latest
distinct images: 1

Four tags and still one image. 1.2.0 never moves. 1.2 moves to the newest patch of that line, and commit-a1b2c3d names the exact code. In Compose and on servers, use 1.2.0 or the commit tag, not latest.

Release the next version

Build 1.2.1 and move 1.2 and latest with it. 1.2.0 stays where it was.

Set-Content version.txt "shop 1.2.1"
docker build -q -t shop-app:1.2.1 -t shop-app:1.2 -t shop-app:latest . | Out-Null
foreach ($t in "1.2.0", "1.2.1", "1.2", "latest") { "{0,-7} -> {1}" -f $t, (docker run --rm "shop-app:$t") }

1.2.0   -> shop 1.2.0
1.2.1   -> shop 1.2.1
1.2     -> shop 1.2.1
latest  -> shop 1.2.1

If 1.2.1 is broken, docker run shop-app:1.2.0 is the rollback, because nobody reused that tag.

Related course: Docker Intermediate.