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

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.

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

Version File

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.

Build script

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.

Release script

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

Travis Reeder

Written by

CTO at GoChain - Advisor at Salesforce - Building and breaking things

Better Programming

Advice for programmers.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade