Setup_remote_docker Architecture Change

We are changing the underlying architecture of the setup_remote_docker feature on the platform. We will be commencing a gradual rollout shortly to experiment with this new architecture after several weeks of successful testing on projects internal to CircleCI.

User impact:

  1. The new architecture should result in faster job execution for the vast majority of users who use setup_remote_docker.
  2. The architecture is significantly simplified and should improve the reliability of jobs that use setup_remote_docker.

At the moment, this rollout excludes jobs that use DLC combined with setup_remote_docker. Those jobs will be included in the rollout at a later date. The new architecture no longer spins up a “remote” Docker engine, but instead runs all Docker commands locally. It will behave very similar to the “Linux VM” execution environment.

If you are seeing issues with jobs that use the setup_remote_docker feature, please submit a support ticket at

Ahead of this change, if you are using the following Remote Docker versions, the recommendation is to use the default version as it is now being kept up-to-date.


This is to avoid a possible a risk of incompatibility with the more current software in the new architecture and the older version of Docker being specified in job’s config file. An email will be sent out to the 10 users who ran the most jobs on CircleCI in the past 30 days and a billing contact for your VCS organization for organizations that have at least one job that is using an older version of Docker.

You can use the default version by eliminating the specific version command in your config.yml.

We just received an email regarding this change but as far as I can see we only use this command in the official CircleCI ECR orb (CircleCI Developer Hub - circleci/aws-ecr). Not sure when this is getting updated to reflect this change but thought I’d highlight it that for some people this might be out of their control.

Issue tracking update to orb in question: update remote docker version to no longer be pinned to an old version · Issue #229 · CircleCI-Public/aws-ecr-orb · GitHub

1 Like

FYI The ECR orb should now be updated to use the default version of Docker.

1 Like

As an FYI, this migration is now complete with the exception of projects that are using an experimental version of Docker. Those projects will be migrated in the short term.

Thank you!

One small update:

Jobs that are using Docker’s Experimental mode will not be supported starting June 1, 2023. We have already been working with customers to find other ways of achieving the same results on CircleCI without Docker’s experimental mode.