Convenience images

This document provides information about convenience images (pre-built Docker images maintained by CircleCI) and a listing by language, service type, and tags.

For convenience, CircleCI maintains several Docker images. These images are typically extensions of official Docker images, and include tools especially useful for CI/CD.

This document provides an overview of best practices when using a convenience image. Please note that we advise using the next-generation convenience images (these start cimg/) rather than legacy images, as explained below.

If you would like to directly search for an image, you can browse CircleCI Docker images in the following locations:

• Visit the Developer Hub for links to all the repositories for each next-gen image.
• Find all CircleCI pre-built images available on Docker Hub.

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

Refer to the Examples and Guides Overview for examples of using pre-built CircleCI Docker Images in a demo application.

The next-generation convenience images in this section were built from the ground up with CI, efficiency, and determinism in mind. Here are some of the highlights:

Faster spin-up time - In Docker terminology, these next-gen images will generally have fewer and smaller layers. Using these new images will lead to faster image downloads when a build starts, and a higher likelihood that the image is already cached on the host.

Improved reliability and stability - The existing legacy convenience images are rebuilt practically every day with potential changes from upstream that we cannot always test fast enough. This leads to frequent breaking changes, which is not the best environment for stable, deterministic builds. Next-gen images will only be rebuilt for security and critical-bugs, leading to more stable and deterministic images.

Using the base image in your config looks like the example shown below:

jobs:
  myjob:
    docker:
      - image: cimg/base:2021.04

This is an Ubuntu-based image designed to install the bare minimum. The next-generation convenience images are based on this image.

When to use it?

If you need a generic image to run on CircleCI, to use with orbs, or to use as a base for your own custom Docker image, this image is for you.

Resources

You can find more config examples for this image on the Developer Hub, and the source code and documentation on GitHub.

The example below demonstrates how to use the next-gen Go image, which is based off the base image above.

jobs:
  myjob:
    docker:
      - image:  cimg/go:1.16

This is a direct replacement for the legacy CircleCI Go image (circleci/golang). Note, the Docker Hub namespace is cimg. You can view other next generation images for other languages below.

The next-gen convenience images in the following sections are based on the most recent Ubuntu LTS Docker images and installed with the base libraries for the language or services, 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.

That is, to prevent unintended changes that come from upstream, instead of using cimg/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, pin down those images to a specific point version, like cimg/ruby:2.4.10-node. Specifying the version is possible for any of the CircleCI images.

It is also possible to use the specific SHA of a image. For example, you can use cimg/ruby@sha256:e4aa60a0a47363eca3bbbb066620f0a5967370f6469f6831ad52231c87ca9390 instead of cimg/ruby:2.4.10-node. Doing so allows you to test specific images for as long as you would like before making any changes.

Note: If you are using a legacy image and 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.

Note: For Node.js variant Docker images (tags that end in -node) the LTS release of Node.js is pre-installed. If you would like to include your own specific version of Node.js / NPM you can set it up in a series of run steps in your .circleci/config.yml. Consider the example below, which installs a specific version of Node.js alongside the Ruby image.

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/ruby:2.7.1-node
    steps:
      - checkout
      - run:
          name: "Update Node.js and npm"
          command: |
            curl -sSL "https://nodejs.org/dist/v11.10.0/node-v11.10.0-linux-x64.tar.xz" | sudo tar --strip-components=2 -xJ -C /usr/local/bin/ node-v11.10.0-linux-x64/bin/node
            curl https://www.npmjs.com/install.sh | sudo bash
      - run:
          name: Check current version of node
          command: node -v

Follow these steps to find your docker image id:

1. In the CircleCI application, navigate to the job in your pipeline for which you would like to know the docker image.
2. Toggle open 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.

cimg/python@sha256:bdabda041f88d40d194c65f6a9e2a2e69ac5632db8ece657b15269700b0182cf

CircleCI’s convenience images fall into two categories:

• language images
• service images

All images add a circleci user as a system user. The sections below walk through the available next-generation and legacy images.

Next-gen language images are convenience images for common programming languages. These images include relevant language tools and commonly-used tools. To use a language image, list it first under the docker key in your configuration, making it the primary container during execution.

See the Developer Hub for a full list of next-gen images.

If your language is not listed, feel free to request an image on our Ideas Board. First, check to see if that “idea” is already on CircleCI Ideas. If it is, up-vote it. If not, create it and set the category as “images”. Finally, go and market your “idea” to friends, co-workers, forums, and other communities in order to help it build traction.

If we see an idea on the board take off, we will consider building it officially.

CircleCI maintains several variants for the next-gen language image. For next-gen images be sure to check each image listing for information on each variant. The -browsers variant for next-gen images is still in progress. See each image listing on the Developer Hub for details on which variants it supports.

The legacy 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 legacy images for the languages below.

• Android
• Clojure
• Elixir
• Go (Golang)
• JRuby
• Node.js
• OpenJDK (Java)
• PHP
• Python
• Ruby
• Rust

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, OpenJDK v11, and Geckodriver
• -node-browsers combines the -node and -browsers 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 are convenience images for services like databases. These images should be listed after language images so they become secondary service containers.

• Postgres
• MySQL
• MariaDB
• Redis

CircleCI maintains legacy images for the services below.

• buildpack-deps
• DynamoDB
• MariaDB
• MongoDB
• MySQL
• PostgreSQL
• Redis

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.

All convenience images have been extended with additional tools, installed with apt-get:

• bzip2
• ca-certificates
• curl
• git
• gnupg
• gzip
• locales
• mercurial (legacy images only)
• net-tools
• netcat
• openssh-client
• parallel
• sudo
• tar
• unzip
• wget
• xvfb (legacy images only)
• 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. The legacy CircleCI convenience images are Debian Jessie- or Stretch-based images, however the next-gen images, cimg, extend the official Ubuntu image. For details on the next-gen images, see the Developer Hub. Each image is tracked in its own repository.

The following packages are pre-installed in convenience images using curl or other means.

• Docker client
• Docker Compose
• dockerize
• jq

1. If an image is not listed above, it is not available. As the convenience image program is revamped, proposals for new images are not currently being accepted.
2. Old versions of software will not be rebuilt. Once an upstream image stops building the tag for a specific release, say Node.js v8.1.0, then we stop building it too. This means other tools in that image, such as npm in this example, will no longer be updated either.
3. We do not support building preview, beta, or release candidate images tags. On occasion they will be available but these tags tend to cause our build system for convenience images to fail. If you need a non-stable release of a language, we suggest installing it via an orb or a custom Docker image instead.

Below is a list of the latest legacy convenience images, sorted by language.

Note: Excluding language image variants and the service image variant, for legacy images 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!

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/android:[TAG]

Recent Tags:

See the tag list for circleci/android on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/buildpack-deps:[TAG]

Recent Tags:

See the tag list for circleci/buildpack-deps on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/clojure:[TAG]

Recent Tags:

See the tag list for circleci/clojure on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/dynamodb:[TAG]

Recent Tags:

See the tag list for circleci/dynamodb on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/elixir:[TAG]

Recent Tags:

See the tag list for circleci/elixir on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/golang:[TAG]

Recent Tags:

See the tag list for circleci/golang on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/jruby:[TAG]

Recent Tags:

See the tag list for circleci/jruby on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/mariadb:[TAG]

Recent Tags:

See the tag list for circleci/mariadb on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/mongo:[TAG]

Recent Tags:

See the tag list for circleci/mongo on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/mysql:[TAG]

Recent Tags:

See the tag list for circleci/mysql on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/node:[TAG]

Recent Tags:

See the tag list for circleci/node on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/openjdk:[TAG]

Recent Tags:

See the tag list for circleci/openjdk on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/php:[TAG]

Recent Tags:

See the tag list for circleci/php on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/postgres:[TAG]

Recent Tags:

See the tag list for circleci/postgres on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/python:[TAG]

Recent Tags:

See the tag list for circleci/python on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/redis:[TAG]

Recent Tags:

See the tag list for circleci/redis on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/ruby:[TAG]

Recent Tags:

See the tag list for circleci/ruby on Docker Hub.

Resources:

• Docker Hub - where this image is hosted as well as some useful instructions.

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

- image: circleci/rust:[TAG]

Recent Tags:

See the tag list for circleci/rust on Docker Hub.

• See Using Docker Authenticated Pulls for information about how to authorize your build to use an image in a private repository or in Amazon ECR.
• For information about macOS images for iOS, see (/docs/testing-ios/).
• See Running Docker Commands for information about how to build Docker images.