Developer
Documentation
circleci.com
Home
Convenience Images
Documentation
circleci.com
  1. Convenience Images
  2. cimg/base

cimg/base

cimg/base is an Ubuntu Docker image created by CircleCI with continuous integration builds in mind. As its name suggests, this image is designed to serve as a base image for other CircleCI Convenience Images (images prefixed with cimg/).

This image is also very useful for CircleCI users to use as a base for their own custom Docker images.

This image contains the minimum tools required to operate a build on CircleCI (such as git) as well as extremely popular and useful tools in CircleCI (such as docker).

Getting Started

This image can be used with the CircleCI docker executor. For example:

1
2
3
4
5
6
7
8
9
jobs:
  build:
    docker:
      - image: cimg/base:2020.10
    steps:
      - checkout
      # Whatever you want to do
      - run: sudo apt-get update && sudo apt-get install -y cowsay
      - run: cowsay Continuous Integration Rocks!

In the above example, the CircleCI Base Docker image is used for the primary container. More specifically, the tag 2020.10 indicates the dated version of the base image. See how tags work below for more information.

How This Image Works

This image contains the Ubuntu Linux operating system and everything needed to run most builds on CircleCI. This includes but is not limited to:

  • Git
  • Docker and Docker Compose
  • Dockerize
  • The build-essential package containing compiling tools
  • jq
  • curl, ssh, and much more

Tagging Scheme

This image has the following tagging scheme:

cimg/base:edge[-version]
cimg/base:stable[-version] 
cimg/base:<YYYY.MM>[-version] 

edge - This image tag points to the latest version of the Base image. This tag is built from the HEAD of the master branch. The edge tag is intended to be used as a testing version of the image with the most recent changes however not guaranteed to be all that stable. This tag is not recommended for production software.

stable - This image tag points to the latest, production ready base image. This image should be used by projects that want a decent level of stability but would like to get occasional software updates. It is typically updated once a month.

<YYYY.MM> - This image tag is a monthly snapshot of the image, referred to by the 4 digit year, dot, and a 2 digit month. For example 2019.09 would be the monthly snapshot tag from September 2019. This tag is intended for projects that are highly sensitive to changes and want the most deterministic builds possible.

-version - This is an optional extension to the tag to specify the version of Ubuntu to use. There can be up to two options, the current LTS and the previous LTS. As of this writing, those options would be 18.04 or 20.04. When leaving the version out, suggested, the default version will be used. The default Ubuntu version is the newest LTS version, after it has been out for 2 months. For example, Ubuntu 20.04 came out in April 2020, so it will become the default version for this image September 2020. The previous LTS version will be supported for a year after it drops out of the default slot.

Image Tags