Fetching contributors…
Cannot retrieve contributors at this time
263 lines (199 sloc) 9.61 KB
layout title short-title description categories order
Pre-Built CircleCI Docker Images
Pre-Built CircleCI Docker Images
Listing of available images maintained by CircleCI

This document provides information about pre-built CircleCI images and a listing by language, service type, and tags in the following sections:

  • TOC {:toc}



For convenience, CircleCI maintains several Docker images. These images are typically extensions of official Docker images and include tools especially useful for CI/CD. All of these pre-built images are available in the CircleCI org on Docker Hub. Visit the circleci-images GitHub repo for the source code for the CircleCI Docker images. Visit the circleci-dockerfiles GitHub repo for the Dockerfiles for the CircleCI Docker images.

Note: CircleCI occasionally makes scheduled changes to images to fix bugs or otherwise improve functionality, and these changes can sometimes cause affect how images work in CircleCI jobs. Please follow the convenience-images tag on Discuss to be notified in advance of scheduled maintenance.

Best Practices

Convenience images are based on the most recently built versions of upstream images, so it is best practice to use the most specific image possible. This makes your builds more deterministic by preventing an upstream image from introducing unintended changes to your image.

CircleCI bases pre-built images off of upstream, for example, circleci/ruby:2.4-node is based off the most up to date version of the Ruby 2.4-node container. Using circleci/ruby:2.4-node is similar to using :latest. It is best practice to lock down aspects of your build container by specifying an additional tag to pin down the image in your configuration.

That is, to prevent unintended changes that come from upstream, instead of using circleci/ruby:2.4-node use a more specific version of these containers to ensure the image does not change with upstream changes until you change the tag.

For example, add -jessie or -stretch to the end of each of those containers to ensure you’re only using that version of the Debian base OS. Pin down those images to a specific point version, like circleci/ruby:2.3.7-jessie, or specify the OS version with circleci/ruby:2.3-jessie. Specifying the version is possible for any of the CircleCI images.

It is also possible to specify all the way down to the specific SHA of the image you want to use. Doing so allows you to test specific images for as long as you like before making any changes.

There are two ways to make an image more specific:

  • Use a tag to pin an image to a version or operating system (OS).
  • Use a Docker image ID to pin an image to a fixed version.

Using an Image Tag to Pin an Image Version or OS


You can pin aspects of a Docker image by adding an image tag.

For example, instead of circleci/golang, specify the version and OS by using circleci/golang:1.8.6-jessie. Because the second image specifies a version and OS, it is less likely to change unexpectedly.

See below for a list of the Latest Image Tags by Language.

Note: If you do not specify a tag, Docker applies the latest tag. The latest tag refers to the most recent stable release of an image. However, since this tag may change unexpectedly, it is best practice to add an explicit image tag.

Using a Docker Image ID to Pin an Image to a Fixed Version


Every Docker image has a unique ID. You can use this image ID to pin an image to a fixed version.

Each image ID is an immutable SHA256 digest and looks like this:


Finding an Image ID


  1. In the CircleCI application, go to a past build that used the image.
  2. On the Test Summary tab, click the Spin up environment step.
  3. In the log output, locate the digest for the image.
  4. Add the image ID to the image name as shown below.

Image Types

CircleCI's convenience images fall into two categories: language images and service images. All images add a circleci user as a system user.

Note: The images below are based on the most recently built upstream images for their respective languages. Because the most recent images are more likely to change, it is best practice to use a more specific tag.

Language Images


Language images are convenience images for common programming languages. These images include both the relevant language and commonly-used tools. A language image should be listed first under the docker key in your configuration, making it the [primary container]({{ site.baseurl }}/2.0/glossary/#primary-container){:target="_blank"} during execution.

CircleCI maintains images for the languages below.

If your language is not listed, CircleCI also maintains a Dockerfile Wizard you can use to create a custom image.

Language Image Variants


CircleCI maintains several variants for language images. To use these variants, add one of the following suffixes to the end of an image tag.

  • -node includes Node.js for polyglot applications
  • -browsers includes Chrome, Firefox, Java 8, and Geckodriver
  • -browsers-legacy includes Chrome, Firefox, Java 8, and PhantomJS
  • -node-browsers combines the -node and -browsers variants
  • -node-browsers-legacy combines the -node and -browsers-legacy variants

For example, if you want to add browsers to the circleci/golang:1.9 image, use the circleci/golang:1.9-browsers image.

Service Images


Service images are convenience images for services like databases. These images should be listed after language images so they become secondary service containers.

CircleCI maintains images for the services below.

Service Image Variant


CircleCI maintains only one variant for service images. To speed up builds using RAM volume, add the -ram suffix to the end of a service image tag.

For example, if you want the circleci/postgres:9.5-postgis image to use RAM volume, use the circleci/postgres:9.5-postgis-ram image.

Pre-installed Tools

All convenience images have been extended with additional tools.

The following packages are installed via apt-get on every image.

The following packages are installed via curl or other means.

Latest Image Tags by Language

Below is a list of the latest convenience images, sorted by language. For details about the contents of each image, refer to the corresponding Dockerfiles.

Note: Excluding language image variants and the service image variant, CircleCI does not control which tags are used. These tags are chosen and maintained by upstream projects. Do not assume that a given tag has the same meaning across images!

{% assign images = | sort %} {% for image in images %}

{{ image[1].name }}


Usage: Add the following under docker: in your config.yml:

- image: circleci/{{ image[0] }}:[TAG]

Latest Tags: (view more available tags on [Docker Hub]({{ image[0] }}/tags/))

    {% assign tags = image[1].tags | sort %} {% for tag in tags %}
  • {{ tag }}
  • {% endfor %}

{% endfor %}

See Also


See [Using Private Images]({{ site.baseurl }}/2.0/private-images/) for information about how to authorize your build to use an image in a private repository or in Amazon ECR.