> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# Convenience images

**Legacy images with the prefix `circleci/` [are deprecated](https://discuss.circleci.com/t/legacy-convenience-image-deprecation/41034)** as of December 31, 2021. For faster builds, upgrade your projects with [next-generation convenience images](https://circleci.com/blog/announcing-our-next-generation-convenience-images-smaller-faster-more-deterministic/).

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

## 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.

This document provides an overview of best practices when using a convenience image. 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](https://circleci.com/developer/images/) for links to all the repositories for each next-gen image.
    
*   Find all CircleCI pre-built images available on [Docker Hub](https://hub.docker.com/u/cimg).
    

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. Follow the [**convenience-images** tag on Discuss](https://discuss.circleci.com/tags/convenience-images) to be notified in advance of scheduled maintenance.

### Examples

Refer to the [Examples and Guides Overview](https://circleci.com/docs/guides/toolkit/examples-and-guides-overview/) for examples of using pre-built CircleCI Docker Images in a demo application.

## Next-generation convenience images

The next-generation convenience images in this section are 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.

### CircleCI base image

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

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

**Using Docker?** Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information, see [Using Docker Authenticated Pulls](https://circleci.com/docs/guides/execution-managed/private-images/).

`cimg/base:2021.04` 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 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](https://circleci.com/developer/images/image/cimg/base), and the source code and documentation on [GitHub](https://github.com/CircleCI-Public/cimg-base).

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

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

This Go image 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](#next-gen-language-images).

## Best practices

The next-gen convenience images in the following sections are based on the most recent Ubuntu LTS Docker images. Next-gen images have base libraries for languages and/or services. It is best practice to use the most specific image possible to make your builds more deterministic by preventing an upstream image from introducing unintended changes to your image.

To prevent unintended changes from upstream, instead of using `cimg/ruby:2.4-node` use a more specific version of these containers. This ensures 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 an 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.

### Notes on pinning images

*   It is not recommended that you use the SHA for extended periods of time. If there is a major bug or security issue that requires a rebuild of the image, your pipeline’s dependency on the image could inhibit you from acquiring the update that fixes that bug or patches a security issue.
    
*   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.
    
*   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.
    

```yaml
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
```

#### Finding an image id

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.
    

```shell
cimg/python@sha256:bdabda041f88d40d194c65f6a9e2a2e69ac5632db8ece657b15269700b0182cf
```

## Image types

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

Next-gen language images are convenience images for common programming languages. These images include relevant language tools and [commonly-used tools](#pre-installed-tools). To use a language image, list it first under the `docker` key in your configuration, making it the [Primary Container](https://circleci.com/docs/reference/glossary/#primary-container) during execution.

See the [Developer Hub](https://circleci.com/developer/images?imageType=docker) for a full list of next-gen images.

If your language is not listed, feel free to request an image on our [Ideas Board](https://ideas.circleci.com/). 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.

#### Next-gen language image variants

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](https://circleci.com/developer/images/) for details on which variants it supports.

### Legacy language images

The legacy language images are convenience images for common programming languages. These images include both the relevant language and [commonly-used tools](#pre-installed-tools). A language image is listed first under the `docker` key in your configuration, making it the [Primary Container](https://circleci.com/docs/reference/glossary/#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
    

#### 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, 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.

### Next-gen service images

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

*   [PostgreSQL](https://circleci.com/developer/images/image/cimg/postgres)
    
*   [MySQL](https://circleci.com/developer/images/image/cimg/mysql)
    
*   [MariaDB](https://circleci.com/developer/images/image/cimg/mariadb)
    
*   [Redis](https://circleci.com/developer/images/image/cimg/redis)
    

### Legacy service images

CircleCI maintains legacy images for the services below.

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

#### 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, 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 package that gets installed in a CircleCI image variant depends on the default version in the package directory. This depends on the Linux distribution installed in that variant’s base image. The legacy CircleCI convenience images are [Debian](https://packages.debian.org/jessie/) Jessie- or [Stretch](https://packages.debian.org/stretch/)\-based. The next-gen images, `cimg`, extend the official [Ubuntu](https://packages.ubuntu.com) image. For details on the next-gen images, see the [Developer Hub](https://circleci.com/developer/images/).

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

*   [Docker client](https://docs.docker.com/install/)
    
*   [Docker Compose](https://docs.docker.com/compose/overview/)
    
*   [dockerize](https://github.com/jwilder/dockerize)
    
*   [jq](https://stedolan.github.io/jq/)
    

## Out of scope

*   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.
    
*   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.
    
*   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](https://circleci.com/orbs/) or a custom Docker image instead.
    

## Legacy image tags by language

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

It is recommended to use next-generation images when possible. For a list of the latest next-gen convenience images and details about the content of each image, visit the [Developer Hub](https://circleci.com/developer/).

Excluding [language image variants](#language-image-variants) and [the service image variant](#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.

| Image name | Resources | Usage | Tags |
| --- | --- | --- | --- |
| Android | [Docker Hub](https://hub.docker.com/r/circleci/android) | `- image: circleci/android:[TAG]` | [Tags](https://hub.docker.com/r/circleci/android/tags?ordering=last_updated) |
| buildpack-deps | [Docker Hub](https://hub.docker.com/r/circleci/buildpack-deps) | `- image: circleci/buildpack-deps:[TAG]` | [Tags](https://hub.docker.com/r/circleci/buildpack-deps/tags?ordering=last_updated) |
| Clojure | [Docker Hub](https://hub.docker.com/r/circleci/clojure) | `- image: circleci/clojure:[TAG]` | [Tags](https://hub.docker.com/r/circleci/clojure/tags?ordering=last_updated) |
| DynamoDB | [Docker Hub](https://hub.docker.com/r/circleci/dynamodb) | `- image: circleci/dynamodb:[TAG]` | [Tags](https://hub.docker.com/r/circleci/dynamodb/tags?ordering=last_updated) |
| Elixir | [Docker Hub](https://hub.docker.com/r/circleci/elixir) | `- image: circleci/elixir:[TAG]` | [Tags](https://hub.docker.com/r/circleci/elixir/tags?ordering=last_updated) |
| Go (Golang) | [Docker Hub](https://hub.docker.com/r/circleci/golang) | `- image: circleci/golang:[TAG]` | [Tags](https://hub.docker.com/r/circleci/golang/tags?ordering=last_updated) |
| JRuby | [Docker Hub](https://hub.docker.com/r/circleci/jruby) | `- image: circleci/jruby:[TAG]` | [Tags](https://hub.docker.com/r/circleci/jruby/tags?ordering=last_updated) |
| MariaDB | [Docker Hub](https://hub.docker.com/r/circleci/mariadb) | `- image: circleci/mariadb:[TAG]` | [Tags](https://hub.docker.com/r/circleci/mariadb/tags?ordering=last_updated) |
| MongoDB | [Docker Hub](https://hub.docker.com/r/circleci/mongo) | `- image: circleci/mongo:[TAG]` | [Tags](https://hub.docker.com/r/circleci/mongo/tags?ordering=last_updated) |
| MySQL | [Docker Hub](https://hub.docker.com/r/circleci/mysql) | `- image: circleci/mysql:[TAG]` | [Tags](https://hub.docker.com/r/circleci/mysql/tags?ordering=last_updated) |
| Node.js | [Docker Hub](https://hub.docker.com/r/circleci/node) | `- image: circleci/node:[TAG]` | [Tags](https://hub.docker.com/r/circleci/node/tags?ordering=last_updated) |
| OpenJDK | [Docker Hub](https://hub.docker.com/r/circleci/openjdk) | `- image: circleci/openjdk:[TAG]` | [Tags](https://hub.docker.com/r/circleci/openjdk/tags?ordering=last_updated) |
| PHP | [Docker Hub](https://hub.docker.com/r/circleci/php) | `- image: circleci/php:[TAG]` | [Tags](https://hub.docker.com/r/circleci/php/tags?ordering=last_updated) |
| PostgreSQL | [Docker Hub](https://hub.docker.com/r/circleci/postgres) | `- image: circleci/postgres:[TAG]` | [Tags](https://hub.docker.com/r/circleci/postgres/tags?ordering=last_updated) |
| Python | [Docker Hub](https://hub.docker.com/r/circleci/python) | `- image: circleci/python:[TAG]` | [Tags](https://hub.docker.com/r/circleci/python/tags?ordering=last_updated) |
| Redis | [Docker Hub](https://hub.docker.com/r/circleci/redis) | `- image: circleci/redis:[TAG]` | [Tags](https://hub.docker.com/r/circleci/redis/tags?ordering=last_updated) |
| Ruby | [Docker Hub](https://hub.docker.com/r/circleci/ruby) | `- image: circleci/ruby:[TAG]` | [Tags](https://hub.docker.com/r/circleci/ruby/tags?ordering=last_updated) |
| Rust | [Docker Hub](https://hub.docker.com/r/circleci/rust) | `- image: circleci/rust:[TAG]` | [Tags](https://hub.docker.com/r/circleci/rust/tags?ordering=last_updated) |

## Next steps

*   See [Using Docker Authenticated Pulls](https://circleci.com/docs/guides/execution-managed/private-images/) 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 the [Testing iOS](https://circleci.com/docs/guides/test/testing-ios/) page.
    
*   See [Running Docker Commands](https://circleci.com/docs/guides/execution-managed/building-docker-images/) for information about how to build Docker images.