Image Type Time Frame More info
Docker Convenience Images < 24 hours (automated) learn more
Machine Image when needed (manual) learn more
Xcode Image < 7 days (manual) learn more

Docker Convenience Images

The majority of jobs on CircleCI are run with the docker executor. This enables the use of Docker images for a job’s execution environment. While any Docker image on Docker Hub, AWS’s ECR, or GCP’s Container Registry, can be used, we provide a set of images, such as circleci/golang, with pre-installed tools that would be useful in a CI environment. Taking advantage of the layering power of Docker, our images are based on upstream images published by Docker and the Docker community called Docker Library.


Whenever a new release comes out, e.g., the recent Go v1.11 release, the Docker Library community will update the image. In this case, they update the golang image. The length of time this takes is completely at their discretion. Sometimes, images get updated in hours. If there is a blocking GitHub issue, it can take a day or two. Regardless, our Docker Convenience Image Build System will rebuild fresh images from upstream every 24 hours, as needed, using Scheduled Workflows. Thus, once an upstream image is available via the Docker Library, we will have our version within 24 hours.

More information on the Docs Page.

Beta and Release Candidates

Docker provides a lot of flexibility. A benefit of using Docker Library images, and, by extension, CircleCI images, is that many software developers will release tags for non-stable releases. For example, before Go v1.11 came out and the golang/circleci:1.11 image was available, several release candidate (RC) tags had been available for quite awhile. Tags like circleci/golang:1.11rc or circleci/golang:1.11-r2 were available after each of these RCs. This enables you to start testing your software on upcoming versions of a language prior to release day.

Machine Image

The machine executor is typically used when lower-level access is needed that can’t be provided by the docker executor. It is a virtual machine (VM) image as opposed to a Docker/LXC image.

Due to its extremely generic use case, the image isn’t updated nearly as often. It only has some basic building-block tools installed. The machine image has Docker and Docker Composed installed. This is the primary driver for why this image gets periodic updates: to keep pace with Docker.


There is no set schedule for updating this image. It is currently updated approximately once a month, but it can take longer. This image is provided to allow a user full power to install what they need on their VM. Information on what image versions are available for machine can be found on the Docs Page.

macOS Image

The macos executor is the simplest to explain. Rather than deal with month-based version numbers, or even macOS release numbers, we release based on the Xcode version. We have separate images based on the semantic versioning (SemVer) of the Xcode release, such as the Xcode 9.4.1 image.


We release new images when there is a new Xcode release. The cadence is primarily dependant on Apple. Once a version of Xcode is released, we will typically have an image for it within seven days. This time frame is heavily influenced by the changes in the release (e.g., bugfix releases take the least amount of time) and by how close to the weekend Apple releases the update. Available images/supported Xcode versions can be found on the Docs Page.