How to Version Your Docker Images

There are a thousand ways to version Docker images — here is a simple one

Travis Reeder
Oct 3, 2016 · 2 min read
Image for post
Image for post

While there are probably a thousand ways to version your Docker images, I am going to show you a very simple way, using methods that have become quite common. It will ensure your image’s versions match your Git version tags, so you know exactly which code is inside the image.

UPDATE: A more recent article I wrote about versioning is available here.

This tutorial assumes you already have a Dockerfile that builds your image.

First, create a VERSION file with nothing in it but the version numbers:


You want to store this VERSION file in the image for completeness (and because your program can use it to display the version), so add the following to your Dockerfile:


That will add the VERSION file to your WORKDIR.

If you don’t already have a build script, create one and call it The simplest form of this is just to run your docker build:

# docker hub username
# image name
docker build -t $USERNAME/$IMAGE:latest .

You may require some extra build steps there, so go ahead and add them. Or you may have your own build script, in which case you can ignore this script and just change the line in the script below to run your build. Be sure to chmod a+x ./ so you can run it.

Now, let’s create a simple release script called that will bump the version, run the build script, set git tags, push tags to GitHub, build the image, and finally push the image to Docker Hub. You can copy and paste the script below — just make sure to change the values at the top to match your Docker Hub information:

# docker hub username
# image name
# ensure we're up to date
git pull
# bump version
docker run --rm -v "$PWD":/app treeder/bump patch
version=`cat VERSION`
echo "version: $version"
# run build
# tag it
git add -A
git commit -m "version $version"
git tag -a "$version" -m "version $version"
git push
git push --tags
docker tag $USERNAME/$IMAGE:latest $USERNAME/$IMAGE:$version# push it
docker push $USERNAME/$IMAGE:latest
docker push $USERNAME/$IMAGE:$version

Make it executable with chmod a+x ./ then run it with ./ .

There you have it. Every time you do a release, simply run ./ and you will have nicely versioned images that match up with your source code!

Better Programming

Advice for programmers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store