Upcoming Change: Docker Default Switching to Docker 28 This Monday

Ecosystem
1

Hey Everyone!

We wanted to give you a heads up that we are switching docker-default to Docker 28 this Monday. Our goal is to eventually move the default to Docker 29 as well, but more on that below.

What’s changing and when

This Monday, docker-default will be updated to point to Docker 28. If you are not explicitly specifying a Docker version in your config, your jobs will automatically start using Docker 28.

What you should do before Monday

We strongly recommend getting ahead of this change by explicitly pinning your Docker version in your .circleci/config.yml now:

  • Want to move to Docker 28 or 29 today? Pin to docker28 or docker29 and start testing now.
  • Want to stay on Docker 27 after the switch? Pin to docker27 so your jobs are not affected when we change the default.
version: 2.1

jobs:
  build:
    docker:
      - image: cimg/base:2026.03
    steps:
      - setup_remote_docker:
          version: docker28  # or docker27, docker29
      - run: docker run hello-world

Explicitly pinning a version means you stay in control and won’t be impacted by any future default changes.

Why not Docker 29 straight away?

When we previously attempted to set Docker 29 as the default, we found that some convenience images (cimgs) – specifically cimg/redis, cimg/postgres, and cimg/openjdk – ship with an older Docker client that is incompatible with the Docker 29 daemon. Jobs using these images that did not explicitly specify a Docker version started failing with the following error:

[+] Building 0.0s (0/0)  docker:default
ERROR: Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version: driver not connecting
Exited with code exit status 1

Docker 28 passes all our tests including with those cimgs, so it is the safe choice for an interim default. We are working on updated cimgs that will be compatible with Docker 29, and once those are available we will move the default to Docker 29 and post another announcement here.

Summary

Scenario What to do
Want to test Docker 28 or 29 now Pin version: docker28 or version: docker29
Want to stay on Docker 27 after Monday Pin version: docker27
Happy to follow the default No action needed, you’ll be on Docker 28 after Monday

Let us know if you have any questions!