When you pull down a new image from the Docker Hub, chances are you’re going to see an associated tag. For instance, when you pull down the debian image, you will see (after issuing docker pull debian):

Using default tag: latest

What does that tag mean? Why latest? I’ll explain why it’s important to use Docker tags, and why “latest” isn’t always going to be your best bet.

SEE: Docker for Professionals: The Practical Guide (TechRepublic Academy)

What are Docker tags?

Docker tags aren’t the same as file tags. With a file tag, you can assign multiple keywords to a file such that, for example, when you search for “linux”, every file tagged with that keyword will appear. That’s not how we use Docker tags; instead, we tag our images for clarification.

Say you’ve uploaded an image for ubuntu to Docker Hub without tagging the file. This would be akin to Canonical’s Download Ubuntu button linking directly to the file ubuntu.iso–you’d have no idea what version of Ubuntu you were downloading. Is it an .04 release or a .10 release? Is it even the latest iteration? That’s why the Ubuntu files are most often labeled like ubuntu-16.04.1-server-amd64.iso so you know exactly what you’re getting.

A Docker tag is like that 16.0.1-server-amd64 section of the download file–it should tell you exactly what image you are pulling down from the repository.

How to add tags to images

Adding a tag to your image is quite simple because the Docker developers have rolled the necessary tools into the docker command.

For example, you’ve retooled your ubuntu image to be precisely what you need. We’ll say your ubuntu image is for development purposes, and it is version 1, released June 14. Let’s create a tagging system that works with that information. We could use a tag similar to:


This indicates to anyone who understands your versioning system that this is version 1, created on the 14th of June. However, this could cause problems for anyone who doesn’t understand your versioning system; you could make it a bit clearer with something like:


The above assumes a US date notation, so even with that, you could get into trouble, though it does illustrate the point.

How do you tag your images? I’ll assume we’re going with the second option above. The command to tag an image looks like this:

docker tag IMAGE ID image/TAG

IMAGE ID is the 12-character identification string for the image (listed from the Docker images command), and TAG is our newly created versioning tag. So our command to tag the Ubuntu image would be:

docker tag 7b9b13f7b9c0 ubuntu/dev:v1.6.14.2017

I’ve tagged an Ubuntu image with both of the above conventions to illustrate how this looks when you issue the command Docker images (Figure A).

Figure A

What happens with our above convention is that we’ve created a repository named ubuntu/dev and tagged the image v1.6.14.2017. We could expand that and create a repository convention for those that will be pulling your images with the likes of:

  • http:v1.6.14.2017
  • sec:v1.6.14.2017
  • testing:v1.6.14.2017

The list could go on to include whatever you need. The important element here is specificity. It’s one thing to add the tag latest, but what exactly does that mean, especially to someone outside your circle of influence?

Committing, tagging, and pushing

If you plan on pushing the image, you will have to commit the changes you make (tagging it during the commit) and then push the image. An example commit command that would include the tagging is (HUBUSER is your Docker Hub username):

docker commit -m "Updated Ubuntu" -a "Jack Wallen" ubuntu-testing-June HUBUSER/ubuntu_testing:v1.6.14.2017

You would then push the image to your Docker Hub account with the following commands:

docker login
​docker push HUBUSER/ubuntu_testing

The image will show up, and you can view it to see the tag information (Figure B).

Figure B

In order to pull that tagged image, you would issue the command:

docker pull HUBUSER/ubuntu_testing:v1.6.14.2017

Get specific

With Docker tags, the more specific you can get, the better. You don’t want your staff or other Docker users pulling down images from your account and having no idea what the images are or how recently they were created. Get specific to avoid such issues.