How to Update Docker Images to the Latest Version

Published:20 October 2021 - 6 min. read

Block over 3 billion compromised passwords & strengthen your Active Directory password policy. Try Specops Password Policy for free!

Docker images are the basis of Docker containers. As images are the foundation, have you ever wondered how to update Docker containers when a new version of an image is released?

Not a reader? Watch this related video tutorial!
Not seeing the video? Make sure your ad blocker is disabled.

Wonder no more! In this tutorial, you will learn how to update your local Docker image repository and update your containers to a new version without messing things up!


This tutorial will be a hands-on demonstration. If you’d like to follow along, be sure you have the following:

  • Linux environment – The tutorial uses Linux (Ubuntu Focal) to run Docker, but you can also apply the same general steps to Windows or macOS.
  • Install Docker engine 20.10.8 (Linux) or Docker desktop 3.5.2 (macOS and Windows).

Running Idempotent Docker Images

A Docker image contains all the software required to run the application associated with it, including OS packages and dependencies. Docker assembles images through instructions within a file called a Dockerfile, which contains idempotent installation instructions.

An idempotent instruction implies that the image resulting from executing the installation instruction will always result in the same output.

The advantage of building idempotent images is that they are system-independent: the resulting image will always be the same. The container execution will always be the same, too, no matter where execution takes place.

A new image version usually implies some improvements on the instruction for building the Docker container base, for example:

  • A newer version of the application source code can replace the old one;
  • Better management of dependencies: less space required or better performance;
  • Better security: the image has security patches to avoid vulnerabilities.

To get the last benefits from any update in Docker images, you need to know how to update them and apply those updates to your containers.

Updating Local Docker images

To begin with, start by updating a local Docker image. The application in the example python container runs Python code applications. Updating the local Docker image means that applications can rely on the newly updated image.

You first need to know which images are currently available in your local environment. Run the following command to check your local images. The TAG column indicates the available version of the image.

docker images
Example of the command used to list available Docker images
Example of the command used to list available Docker images

Now that you have your local version of the image, you then must find the latest available image on a remote registry. There are multiple remote Docker registries (repositories of Docker images) that the Docker engine queries to update your local images. Docker pulls images from DockerHub by default, but there are multiple alternatives, most of them private. Some alternative repositories are listed below.

Navigate through the repository page and look for your desired image: an official Python image that you will update as an example. Type python to find the desired image in DockerHub, and open it to find the available tags. The examples for this tutorial are of a Python image.

Every tag also has a push date. The push date is the date when the image was uploaded to the registry. Take note of the image tag and name, both of which you will need in the following steps.

Looking for specific tags in the DockerHub website.
Looking for specific tags in the DockerHub website.

Now that you have the newer version tag, it is time to update the image. To update to a newer image, you first need to pull the new version. Run the docker pull command followed by a colon and the name and the tag of the newer image: the name and tag that you took note of previously. The name and tag for the example is python:slim-buster. The full command and the resulting output are shown below.

docker pull python:slim-buster 
Pulling a newer Python image from DockerHub registry.
Pulling a newer Python image from DockerHub registry.

To pull the image from the non-default Docker image registry (DockerHub), you must provide the full image URI instead. For example: to pull Python from (AWS) ECR Public Gallery, run dockerpull

Learning How to Update Docker Containers

Once you create a container, the container image cannot change. Since the image cannot change, you cannot truly update a running container. What you do is recreate any running containers with replacement containers using the newer image version.

Since you already have the more recent version, it’s time to recreate the containers with the old images that need updating.

To find which containers you need to recreate, list any existing containers running the old image. The docker ps command lists containers. With the --filter flag, you specify which containers to list. There are multiple available options for filtering, and the ancestor flag filters by the image used as a base to build the container. The starting containers in the examples are for Python 3.7.2, which you will apply as a filter. The -a switch shows all available containers.

docker ps -a --filter "ancestor=python:3.7.2"
List all existing containers created with the old image.
List all existing containers created with the old image.

You can use the output of docker ps as an input to run the docker stop command on all the listed containers. The flag -q is included, so the listing command only returns the IDs of the containers. The output of the command is the list of IDs of the stopped containers.

docker stop $(docker ps -aq  --filter "ancestor=python:3.7.2")
Stopping all the containers running the old image
Stopping all the containers running the old image

After stopping the containers, you need to ask Docker to effectively delete them from the system before removing the outdated image.

docker rm $(docker ps -aq --filter "ancestor=python:3.7.2")
Removing the stopped containers that were created using the outdated image.
Removing the stopped containers that were created using the outdated image.

After removing all the containers associated with the deprecated image, you can remove the old image with the docker rmi command.

docker rmi python:3.7.2
Removing deprecated image with the docker rmi command.
Removing deprecated image with the docker rmi command.

Creating New Containers with the Update Images

Now it’s time to finally replace the old containers, those that were previously deleted, with new containers based on the updated image. This time, you’ll create the containers using the newer image version. Since the containers are idempotent, you can expect everything to work as before.

Run the new container with the docker run command and the name and the tag of the updated image that the container will need. In this example, the -it flag tells Docker to run the container in interactive mode, so you can run commands inside the container to verify any updated functionality.

docker run -it python:slim-buster
Running the updated Docker container.
Running the updated Docker container.

Notice that the new Docker container is running a newer Python version: version 3.9.7.


In this tutorial, you took a peek behind the covers and learned the magic behind how to update Docker containers: smoke and mirrors! There is no updating! Instead, remove all traces of the old version and replace them with new containers using a newer version. And, thanks to idempotency, containers keep working as usual: TA-DA!

So, what are the containers you are planning to update next?

Hate ads? Want to support the writer? Get many of our tutorials packaged as an ATA Guidebook.

Explore ATA Guidebooks

Looks like you're offline!