Pre-Built CircleCI Docker Images
This document provides information about pre-built CircleCI images and a listing by language, service type, and tags in the following sections:
Overview
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:
sha256:df1808e61a9c32d0ec110960fed213ab2339451ca88941e9be01a03adc98396e
Finding an Image ID
- In the CircleCI application, go to a past build that used the image.
- On the Test Summary tab, click the Spin up environment step.
- In the log output, locate the digest for the image.
- Add the image ID to the image name as shown below.
circleci/ruby@sha256:df1808e61a9c32d0ec110960fed213ab2339451ca88941e9be01a03adc98396e
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 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.
With the exception of Android images,
all images include the following packages, installed via apt-get
:
bzip2
ca-certificates
curl
git
gnupg
gzip
locales
mercurial
net-tools
netcat
openssh-client
parallel
sudo
tar
unzip
wget
xvfb
zip
The specific version of a particular package that gets installed in a particular CircleCI image variant depends on the default version included in the package directory for the Linux distribution/version installed in that variant’s base image. Most CircleCI convenience images are Debian Jessie- or Stretch-based images, however some extend Ubuntu-based images. For details on individual variants of CircleCI images, see the circleci-dockerfiles repository.
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!
Android
Usage: Add the following under docker:
in your config.yml:
- image: circleci/android:[TAG]
Latest Tags: (view more available tags on Docker Hub)
- api-23
- api-23-alpha
- api-23-ndk
- api-23-ndk-r17b
- api-24
- api-24-alpha
- api-24-ndk
- api-24-ndk-r17b
- api-25
- api-25-alpha
- api-25-ndk
- api-25-ndk-r17b
- api-26
- api-26-alpha
- api-26-ndk
- api-26-ndk-r17b
- api-27
- api-27-alpha
- api-27-ndk
- api-27-ndk-r17b
- api-28
- api-28-alpha
- api-28-ndk
- api-28-ndk-r17b
- example
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
buildpack-deps
Usage: Add the following under docker:
in your config.yml:
- image: circleci/buildpack-deps:[TAG]
Latest Tags: (view more available tags on Docker Hub)
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
Clojure
Usage: Add the following under docker:
in your config.yml:
- image: circleci/clojure:[TAG]
Latest Tags: (view more available tags on Docker Hub)
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
DynamoDB
Usage: Add the following under docker:
in your config.yml:
- image: circleci/dynamodb:[TAG]
Latest Tags: (view more available tags on Docker Hub)
- 11-jdk-oracle
- 11-jdk-oraclelinux7
- 11-jdk-stretch
- 11-jre-stretch
- 11-oracle
- 11-oraclelinux7
- 11-stretch
- 11.0-jdk-oracle
- 11.0-jdk-oraclelinux7
- 11.0-jdk-stretch
- 11.0-oracle
- 11.0-oraclelinux7
- 11.0-stretch
- 11.0.1-jdk-stretch
- 11.0.1-stretch
- 11.0.2-jdk-oracle
- 11.0.2-jdk-oraclelinux7
- 11.0.2-oracle
- 11.0.2-oraclelinux7
- 12-ea-29-jdk-oracle
- 12-ea-29-jdk-oraclelinux7
- 12-ea-29-oracle
- 12-ea-29-oraclelinux7
- 12-ea-jdk-oracle
- 12-ea-jdk-oraclelinux7
- 12-ea-oracle
- 12-ea-oraclelinux7
- 12-jdk-oracle
- 12-jdk-oraclelinux7
- 12-oracle
- 12-oraclelinux7
- 13-ea-5-jdk-oracle
- 13-ea-5-jdk-oraclelinux7
- 13-ea-5-oracle
- 13-ea-5-oraclelinux7
- 13-ea-jdk-oracle
- 13-ea-jdk-oraclelinux7
- 13-ea-oracle
- 13-ea-oraclelinux7
- 13-jdk-oracle
- 13-jdk-oraclelinux7
- 13-oracle
- 13-oraclelinux7
- jdk-oracle
- jdk-oraclelinux7
- jdk-stretch
- jre-stretch
- oracle
- oraclelinux7
- stretch
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
Elixir
Usage: Add the following under docker:
in your config.yml:
- image: circleci/elixir:[TAG]
Latest Tags: (view more available tags on Docker Hub)
- 1.5
- 1.5.3
- 1.7
- 1.7.4
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
Go (Golang)
Usage: Add the following under docker:
in your config.yml:
- image: circleci/golang:[TAG]
Latest Tags: (view more available tags on Docker Hub)
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
JRuby
Usage: Add the following under docker:
in your config.yml:
- image: circleci/jruby:[TAG]
Latest Tags: (view more available tags on Docker Hub)
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
MariaDB
Usage: Add the following under docker:
in your config.yml:
- image: circleci/mariadb:[TAG]
Latest Tags: (view more available tags on Docker Hub)
- 10
- 10-bionic
- 10-bionic-ram
- 10-ram
- 10.0
- 10.0-ram
- 10.0-xenial
- 10.0-xenial-ram
- 10.0.37
- 10.0.37-ram
- 10.0.37-xenial
- 10.0.37-xenial-ram
- 10.1
- 10.1-bionic
- 10.1-bionic-ram
- 10.1-ram
- 10.1.37
- 10.1.37-bionic
- 10.1.37-bionic-ram
- 10.1.37-ram
- 10.2
- 10.2-bionic
- 10.2-bionic-ram
- 10.2-ram
- 10.2.21
- 10.2.21-bionic
- 10.2.21-bionic-ram
- 10.2.21-ram
- 10.3
- 10.3-bionic
- 10.3-bionic-ram
- 10.3-ram
- 10.3.12
- 10.3.12-bionic
- 10.3.12-bionic-ram
- 10.3.12-ram
- 10.4-bionic-ram
- 10.4-ram
- 10.4.2-bionic-ram
- 10.4.2-ram
- 5-ram
- 5-trusty-ram
- 5.5-ram
- 5.5-trusty-ram
- 5.5.62-ram
- 5.5.62-trusty-ram
- bionic
- bionic-ram
- latest
- latest-ram
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
MongoDB
Usage: Add the following under docker:
in your config.yml:
- image: circleci/mongo:[TAG]
Latest Tags: (view more available tags on Docker Hub)
- 3
- 3-ram
- 3-stretch
- 3-stretch-ram
- 3.4
- 3.4-jessie
- 3.4-jessie-ram
- 3.4-ram
- 3.4.18-jessie-ram
- 3.4.19
- 3.4.19-jessie
- 3.4.19-jessie-ram
- 3.4.19-ram
- 3.6
- 3.6-ram
- 3.6-stretch
- 3.6-stretch-ram
- 3.6.10
- 3.6.10-ram
- 3.6.10-stretch
- 3.6.10-stretch-ram
- 4
- 4-ram
- 4-xenial
- 4-xenial-ram
- 4.0
- 4.0-ram
- 4.0-xenial
- 4.0-xenial-ram
- 4.0.5
- 4.0.5-ram
- 4.0.5-xenial
- 4.0.5-xenial-ram
- 4.1
- 4.1-ram
- 4.1-xenial
- 4.1-xenial-ram
- 4.1.7
- 4.1.7-ram
- 4.1.7-xenial
- 4.1.7-xenial-ram
- example
- latest
- latest-ram
- unstable
- unstable-ram
- unstable-xenial
- unstable-xenial-ram
- xenial
- xenial-ram
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
MySQL
Usage: Add the following under docker:
in your config.yml:
- image: circleci/mysql:[TAG]
Latest Tags: (view more available tags on Docker Hub)
- 5
- 5-ram
- 5.5
- 5.5-ram
- 5.5.59-ram
- 5.5.60
- 5.5.60-ram
- 5.5.61
- 5.5.61-ram
- 5.5.62
- 5.5.62-ram
- 5.6
- 5.6-ram
- 5.6.39-ram
- 5.6.40
- 5.6.40-ram
- 5.6.41
- 5.6.41-ram
- 5.6.42
- 5.6.42-ram
- 5.6.43
- 5.6.43-ram
- 5.7
- 5.7-ram
- 5.7.21-ram
- 5.7.22
- 5.7.22-ram
- 5.7.23
- 5.7.23-ram
- 5.7.24
- 5.7.24-ram
- 5.7.25
- 5.7.25-ram
- 8
- 8-ram
- 8.0
- 8.0-ram
- 8.0.11
- 8.0.11-ram
- 8.0.12
- 8.0.12-ram
- 8.0.13
- 8.0.13-ram
- 8.0.14
- 8.0.14-ram
- 8.0.4
- 8.0.4-ram
- 8.0.4-rc-ram
- latest
- latest-ram
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
Node.js
Usage: Add the following under docker:
in your config.yml:
- image: circleci/node:[TAG]
Latest Tags: (view more available tags on Docker Hub)
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
OpenJDK
Usage: Add the following under docker:
in your config.yml:
- image: circleci/openjdk:[TAG]
Latest Tags: (view more available tags on Docker Hub)
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
PHP
Usage: Add the following under docker:
in your config.yml:
- image: circleci/php:[TAG]
Latest Tags: (view more available tags on Docker Hub)
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
PostgreSQL
Usage: Add the following under docker:
in your config.yml:
- image: circleci/postgres:[TAG]
Latest Tags: (view more available tags on Docker Hub)
- 10-alpine-postgis
- 10-alpine-postgis-ram
- 10-alpine-ram
- 10-postgis-ram
- 10.6-alpine-postgis
- 10.6-alpine-postgis-ram
- 10.6-alpine-ram
- 10.6-postgis-ram
- 11-alpine-postgis
- 11-alpine-postgis-ram
- 11-alpine-ram
- 11-postgis-ram
- 11.1-alpine-postgis
- 11.1-alpine-postgis-ram
- 11.1-alpine-ram
- 11.1-postgis-ram
- 9-alpine-postgis
- 9-alpine-postgis-ram
- 9-alpine-ram
- 9-postgis
- 9-postgis-ram
- 9.4-alpine-postgis
- 9.4-alpine-postgis-ram
- 9.4-alpine-ram
- 9.4-postgis-ram
- 9.4.20-alpine-postgis
- 9.4.20-alpine-postgis-ram
- 9.4.20-alpine-ram
- 9.4.20-postgis-ram
- 9.5-alpine-postgis
- 9.5-alpine-postgis-ram
- 9.5-alpine-ram
- 9.5-postgis-ram
- 9.5.15-alpine-postgis
- 9.5.15-alpine-postgis-ram
- 9.5.15-alpine-ram
- 9.5.15-postgis-ram
- 9.6-alpine-postgis
- 9.6-alpine-postgis-ram
- 9.6-alpine-ram
- 9.6-postgis
- 9.6-postgis-ram
- 9.6.11-alpine-postgis
- 9.6.11-alpine-postgis-ram
- 9.6.11-alpine-ram
- 9.6.11-postgis-ram
- alpine-postgis
- alpine-postgis-ram
- alpine-ram
- latest-postgis-ram
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
Python
Usage: Add the following under docker:
in your config.yml:
- image: circleci/python:[TAG]
Latest Tags: (view more available tags on Docker Hub)
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
Redis
Usage: Add the following under docker:
in your config.yml:
- image: circleci/redis:[TAG]
Latest Tags: (view more available tags on Docker Hub)
- 32bit
- 32bit-stretch
- 4
- 4-32bit
- 4-32bit-stretch
- 4-alpine
- 4-alpine3.8
- 4-stretch
- 4.0
- 4.0-32bit
- 4.0-32bit-stretch
- 4.0-alpine
- 4.0-alpine3.8
- 4.0-stretch
- 4.0.11-alpine3.8
- 4.0.12
- 4.0.12-32bit
- 4.0.12-32bit-stretch
- 4.0.12-alpine
- 4.0.12-alpine3.8
- 4.0.12-stretch
- 5
- 5-32bit
- 5-32bit-stretch
- 5-alpine
- 5-alpine3.8
- 5-stretch
- 5.0
- 5.0-32bit
- 5.0-32bit-stretch
- 5.0-alpine
- 5.0-alpine3.8
- 5.0-stretch
- 5.0.2
- 5.0.2-32bit
- 5.0.2-32bit-stretch
- 5.0.2-alpine
- 5.0.2-alpine3.8
- 5.0.2-stretch
- 5.0.3
- 5.0.3-32bit
- 5.0.3-32bit-stretch
- 5.0.3-alpine
- 5.0.3-alpine3.8
- 5.0.3-stretch
- alpine
- alpine3.8
- example
- latest
- stretch
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
Ruby
Usage: Add the following under docker:
in your config.yml:
- image: circleci/ruby:[TAG]
Latest Tags: (view more available tags on Docker Hub)
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
Rust
Usage: Add the following under docker:
in your config.yml:
- image: circleci/rust:[TAG]
Latest Tags: (view more available tags on Docker Hub)
- 1
- 1-stretch
- 1.32
- 1.32-stretch
- 1.32.0
- 1.32.0-stretch
- example
- latest
- stretch
Note: Any variants available for this image can be added by appending the variant tag to the tags above.
See Also
See Using Private Images for information about how to authorize your build to use an image in a private repository or in Amazon ECR.