How to Update a Docker Image | Step-by-Step Guide

Updating a Docker image means pulling a newer version, stopping any containers running the old version, removing those containers, and starting new ones from the updated image. Docker does not automatically update images in running containers. You must replace containers manually or use automation tools.

In this guide, you will learn how to update Docker images pulled from registries like Docker Hub, rebuild custom images from a Dockerfile, update services managed with Docker Compose, and clean up old images.

#Prerequisites

Before you start this tutorial, make sure that:

• You have the latest version of Ubuntu installed on your system.

• Docker is installed on your host machine.

• Your account has admin rights.

• You have at least one Docker image and a running container to work with.

• You have a stable internet connection to pull images from a registry.

#What is a Docker image?

A Docker image is a read-only template that contains everything needed to run an application: code, runtime, system libraries, and configuration files.

Docker is a platform that enables developers to package everything an application needs to run, including the code, runtime, and libraries, into an executable software package called a Docker image. This image can then be used to run or launch containers.

Containers are isolated runtime instances of images. They run consistently across different environments, from local development machines to production servers.

Docker images are built in layers. Each layer represents a set of filesystem changes from a Dockerfile instruction. When you update an image, Docker only downloads the layers that changed, making pulls faster and saving disk space.

You can build Docker images locally from a Dockerfile or pull pre-built images from registries like Docker Hub.

#Why update Docker images?

Outdated Docker images expose your applications to known security vulnerabilities and missed performance improvements. Docker images need regular updates. Ignoring them can result in security risks, compatibility issues, and performance issues. Here are four key reasons to keep your images up to date.

• Updating to new dependency packages: A Docker image depends on many external libraries and components. These components get updates from time to time. Some of the updates include critical security updates and performance optimization. By updating to the latest dependency package, you reduce vulnerabilities detected in the previous version and upgrade functionality.

• Performance improvements: Image updates often include optimizations such as reduced image size, faster container startup times, and better resource management. These performance improvements can lead to more efficient use of hardware resources, quicker deployment times, and an overall smoother operation in production environments.

• Application bug fixes: Whenever you release a new application version that contains bug fixes and UI optimizations, you have to build and update the Docker image used to launch the container. You can rebuild the image using docker build and then recreate the container from the new image.

• Security patches for base images: Base images like ubuntu, alpine, or node receive frequent security patches. Running containers on outdated base images leaves your application vulnerable to exploits that have already been fixed upstream. Regularly pulling and rebuilding against updated base images closes these gaps.

#How to update a Docker image: Step-by-step process

Docker containers are immutable. Once a container starts from an image, it keeps using that exact version for its entire lifecycle. Even after a newer version of the image becomes available in the registry, the running container does not change. To apply an updated image, you must stop the old container, remove it, and create a new container from the latest image.

The following steps demonstrate the process using an Nginx image as an example.

#Step 1: Confirm the version of the current Docker image

First, you need to confirm the version of the particular Docker image you want to update. To list the Docker images on your system, run:

docker images

You will get the following output that shows available images:

OutputIMAGE              ID        DISK USAGE  CONTENT SIZE EXTRA

hello-world:latest 1b44b5a3e06a  10.1kB            0B  U

nginx:latest       5cdef4ac3335   161MB            0B

sampleapp:v1       d484b7e19e06  12.6MB            0B  U

Additionally, the docker inspect command is especially useful when the tag says "latest" because "latest" does not tell you the actual version number.

docker inspect <IMAGE ID>

In the Env section of the output, you should see the version of the image.

Output[  
{  
"Id": "sha256:5cdef4ac3335f68428701c14c5f12992f5e3669ce8ab7309257d263eb7a856b1",  
"RepoTags": [  
"nginx:latest"  
],  
"RepoDigests": [  
"nginx@sha256:341bf0f3ce6c5277d6002cf6e1fb0319fa4252add24ab6a0e262e0056d313208"  
],  
"Comment": "buildkit.dockerfile.v0",  
"Created": "2026-02-04T23:53:09.258787756Z",  
"Config": {  
"ExposedPorts": {  
"80/tcp": {}  
},  
"Env": [  
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",  
"NGINX_VERSION=1.29.5",  
"NJS_VERSION=0.9.5",  
"NJS_RELEASE=1~trixie",  
"ACME_VERSION=0.3.1",  
"PKG_RELEASE=1~trixie",  
"DYNPKG_RELEASE=1~trixie"  
],  
…  
]

You can also filter the output to show only the version-related environment variable:

docker inspect --format='' <IMAGE ID>

OutputPATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin  
NGINX_VERSION=1.29.5  
NJS_VERSION=0.9.5  
NJS_RELEASE=1~trixie  
ACME_VERSION=0.3.1  
PKG_RELEASE=1~trixie  
DYNPKG_RELEASE=1~trixie

#Step 2: Pull the latest Docker image

Next, you need to find out what the latest version of the Docker image is and pull the image to your Docker environment. You can check DockerHub for the latest images. For this, we're using the Nginx repository on Docker Hub.

Start by navigating to the Nginx repository. From the "Tags" tab, you can see the different image tags. You'd usually just pull the image with the "latest" tag, but it's best to pull using the version number. Pinning a specific version tag gives you control over exactly which release your containers use. The "latest" tag can shift to a new major version without warning, which may break your application.

Now, to pull this version of Nginx from the registry, run:

docker pull nginx:stable-alpine3.23-perl

Outputstable-alpine3.23-perl: Pulling from library/nginx  
589002ba0eae: Already exists  
800b59f22ca0: Already exists  
1ccbcb6eec86: Already exists  
7d613b3ef0c9: Already exists  
9239ea08142f: Already exists  
8c0ebebf0171: Already exists  
06400c1243d8: Already exists  
eeece45bc9a6: Pull complete  
18fcc6ddf419: Pull complete  
Digest: sha256:57e903d5641d80334bd51985b8bcecad80d36b30cd0b6408b851333fca1d88bf  
Status: Downloaded newer image for nginx:stable-alpine3.23-perl  
docker.io/library/nginx:stable-alpine3.23-perl

#Step 3: Stop and remove running containers

Next, check containers running with the older image using:

docker ps

This command will list containers running on your Docker system.

From the output, you will see that one container is using an older Nginx image. Copy the container ID, as you would need this to stop and remove the container. To stop and remove the container, start by stopping the container:

docker stop <CONTAINER ID>

Next, remove the container using its ID.

docker rm <CONTAINER ID>

If the container is removed successfully, its ID will be displayed in the output.

You can also combine the stop and remove steps into a single command:

docker rm -f <CONTAINER ID>

The -f flag forces the container to stop (sends SIGKILL) and then removes it. Use this for non-production scenarios where graceful shutdown is not critical.

Warning: Removing a container deletes all data stored inside it. Any files written to the container's writable layer will be lost. If your container stores important data such as logs, uploads, or database files, make sure you use Docker volumes to persist that data outside the container before removing it.

You can also delete the old image using the docker rmi command like so:

docker rmi <IMAGE ID>

#Step 4: Create and run containers with the updated image

Since you've pulled the latest version of nginx, you can create containers with the new image using the docker run command:

docker run -d nginx:stable-alpine3.23-perl

This will run the container in the background, printing out the container ID in the terminal.

To confirm that the container you just ran is using the new version, check the running containers using:

docker ps

OutputCONTAINER ID IMAGE                        COMMAND                  CREATED       STATUS       PORTS  NAMES  
7d31cbc25f7d nginx:stable-alpine3.23-perl "/docker-entrypoint...." 6 seconds ago Up 5 seconds 80/tcp eager_hawking

Important: When recreating the container, apply the same flags and configurations you used with the old container. Port mappings (-p), volume mounts (-v), environment variables (-e), network settings, and restart policies must all match. Otherwise, the new container will behave differently from the previous one.

For example, if your original container mapped port 80 and used a volume for Nginx content:

docker run -d -p 80:80 -v /var/www/html:/usr/share/nginx/html --name my-nginx nginx:stable-alpine3.23-perl

Also read: How to push an image to DockerHub

#How to update a custom Docker image

The steps above apply to images pulled from a registry. If you built your image locally from a Dockerfile, the update process is different. You rebuild the image from the updated Dockerfile and then replace the container.

#Step 1: Update the Dockerfile or application code

Make the necessary changes to your application code, dependencies, or the Dockerfile itself. Common updates include bumping the base image version, adding new packages, or copying updated source code.

For example, to update the base image from an older Node.js version to a newer one:

# Before  
FROM node:18-alpine  
  
# After  
FROM node:22-alpine

#Step 2: Rebuild the image

Run the docker build command with the --no-cache flag to force Docker to pull fresh base image layers and re-run all instructions:

docker build --no-cache -t my-app:latest .

Without --no-cache, Docker reuses cached layers. Cached layers can mask updates in the base image or in downloaded packages. The --no-cache flag ensures every layer rebuilds from scratch.

If you only want to refresh the base image without rebuilding all layers, use --pull instead:

docker build --pull -t my-app:latest .

The --pull flag tells Docker to always pull the latest version of the base image specified in the FROM instruction. Layers after the FROM instruction still use the cache unless the base image changed.

#Step 3: Replace the running container

Follow the same stop, remove, and recreate process from Steps 3 and 4 above:

docker stop my-app-container  
docker rm my-app-container  
docker run -d --name my-app-container -p 3000:3000 my-app:latest

#How to update Docker images with Docker Compose

Docker Compose simplifies the update process for multi-container applications. Instead of stopping, removing, and recreating containers individually, Compose handles it all with two commands.

#Pull updated images

Run this command from the directory that contains your docker-compose.yml file:

docker compose pull

Docker Compose checks the registry for newer versions of every image specified in the file and downloads any updates.

#Recreate containers with updated images

After pulling, recreate only the containers whose images changed:

docker compose up -d

The -d flag runs containers in detached mode. Docker Compose compares the current container image with the pulled image. If the image changed, Compose stops the old container and starts a new one automatically. Containers with unchanged images remain untouched.

For a custom image built from a Dockerfile in your Compose file, add the --build flag:

docker compose up -d --build

The full update sequence for a Compose project:

docker compose pull  
docker compose up -d  
docker image prune -f

The last command removes any old, unused images left behind after the update.

#How to clean up old Docker images

Every time you pull or build a new version of an image, the old version stays on disk. Over time, these unused images consume significant storage space. Docker provides several commands for cleanup.

#Remove a specific old image

docker rmi <IMAGE ID>

#Remove all unused images

docker image prune -a

The -a flag removes all images not associated with a running container. Without -a, Docker only removes "dangling" images (untagged layers left behind by builds).

#Remove everything unused

docker system prune -a --volumes

For more details on image removal, read the full guide on how to remove Docker images.

#Troubleshooting

#Image pull fails with "manifest not found"

The tag you specified does not exist in the registry. Double-check the tag name and version number on Docker Hub. Tags are case-sensitive.

#Container fails to start after update

The new image version may have changed configuration paths, default ports, or environment variable names. Check the image's release notes or changelog on Docker Hub. Run docker logs <CONTAINER ID> to view error messages from the container.

#Old image cannot be removed

If you see "image is referenced in multiple repositories," the image is tagged under multiple names. Remove all tags first, or use docker rmi -f <IMAGE ID> to force removal.

#"No space left on device" when pulling new images

Old images and build cache are consuming disk space. Run docker system prune -a to free space. On systems with heavy Docker usage, schedule regular cleanups or set Docker's storage limit in /etc/docker/daemon.json.

#Port conflict after recreating a container

The old container may still be occupying the port if it was not fully removed. Run docker ps -a to check for stopped containers still using the port, then remove them with docker rm <CONTAINER ID>.

#Conclusion

Updating Docker images involves pulling or rebuilding the image, stopping and removing old containers, and starting new containers from the updated version. For registry images, use docker pull followed by container replacement. For custom images, rebuild with docker build --no-cache. Docker Compose simplifies the process to docker compose pull followed by docker compose up -d. Watchtower adds automation for development and home lab environments.

Keep your images up to date to benefit from security patches, bug fixes, and performance improvements. Pair regular updates with image cleanup (docker image prune) to prevent unused images from filling your disk. For complex production deployments, integrate image updates into your CI/CD pipeline for controlled rollouts with rollback support.

For more on managing Docker containers and images, explore our guides on Docker commands and Docker Compose for multi-container applications.