How to Update Docker Container and Compose Stacks

Docker is a platform that allows developers to easily create, deploy, and run applications in containers. Containers are a way to package software so that it can run consistently across different environments, like your computer, a server, or even the cloud.

Containers are lightweight, efficient, use less resources than traditional VMs and shares the host system’s kernel and libraries.

To update a docker container or a docker compose stack, you need to pull the new version (image) from Docker Hub or any other container registry and re-create the container using the new image. Container data found in volumes will not be lost during container re-creation. Follow these steps to update any docker container or stack.

Update a single Docker container

Pull the new image using docker pull. You can download specific version by adding its tag to the image name mysql:8.1.0, or don’t specify a version to download latest:

1
docker pull louislam/uptime-kuma

Stop then remove the existing running container:

1
2
docker container stop uptime-kuma
docker container rm uptime-kuma

Re-create the container:

1
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma

If you forgot the docker run command you used to create the original container, search for it in the terminal history:

1
history | grep "docker run"

Update a Docker compose stack

Navigate to the directory where the stack .yaml file is located:

1
cd /home/elastic/docker

Pull the new images from the yaml file. By default this command will use compose.yaml or docker-compose.yaml:

1
docker compose pull

Re-create the containers using the up command, in detached mode:

1
docker compose up -d

If you are using a yaml file with a different name than compose.yaml or docker-compose.yaml, make sure to specify the file name using the -f flag:

1
2
3
4
5
6
7
8
9
docker compose -f pi.yaml pull

[+] Pulling 1/1
 ✔ pihole Pulled                                                                                                   0.5s

docker compose -f pi.yaml up -d

[+] Running 1/1
 ✔ Container pihole  Started                                                                                       5.3s

If you want to force Compose to stop and recreate all containers, even if they had no new images available, use the --force-recreate flag:

1
docker compose up -d --force-recreate

From July 2023 Compose V1 stopped receiving updates. It’s also no longer available in new releases of Docker Desktop.

Delete old images to free disk space

List docker images:

1
2
3
4
5
6
7
docker image ls

REPOSITORY             TAG       IMAGE ID       CREATED        SIZE
louislam/uptime-kuma   latest    fb3a3565b2da   5 days ago     431MB
louislam/uptime-kuma   1         c75c443c4b9a   7 weeks ago    484MB
pihole/pihole          latest    566a5a3d4773   2 months ago   301MB
pihole/pihole          <none>    4d6ef5c6684a   5 months ago   324MB

Delete one or multiple images using the first few unique letters of the IMAGE ID:

1
2
3
4
5
6
7
docker image rm c75 4d

Untagged: louislam/uptime-kuma:1
Untagged: louislam/uptime-kuma@sha256:0b55bcb83a1c46c6f08bcc0329fc6c1d86039581102ec8db896976a9d46de01d
Deleted: sha256:c75c443c4b9afc5b3bed698692c96318e45413c8ab866b5864432ae7e522185b
Untagged: pihole/pihole@sha256:a74dde4800f54d3c0b0839babbac9f2cc7e4b8239ab4a5bc2c25c7328ec1c019
Deleted: sha256:4d6ef5c6684a8f5ce05e684dd1b92d75dfb1bbfeec2b8cf9a475fdbe71de2f07

Verify unused images are deleted:

1
2
3
4
docker image ls
REPOSITORY             TAG       IMAGE ID       CREATED        SIZE
louislam/uptime-kuma   latest    fb3a3565b2da   5 days ago     431MB
pihole/pihole          latest    566a5a3d4773   2 months ago   301MB

Tip: You can cleanup all unused images in your host by using the command docker image prune --all.