Ubuntu 20.04 & Next-Gen Convenience Images

Beginning this month we have begun Ubuntu 20.04 availability in next-gen Convenience Images. The CircleCI Base Image (cimg/base) now has both Ubuntu 18.04 and Ubuntu 20.04 versions. How this may or may not affect you depends on if you’re using the base image directly or if you are using a language image. Language images are the Go, Node.js, Ruby, etc next-gen Convenience Images. Information for the base image is the next section. To skip to information for languages images, click here.

The CircleCI Base Image (cimg/base)

For projects running on the base image directly, or anyone building custom Docker images based on the base image, this section is for you.

The availability of Ubuntu 20.04 directly affects the base image. We now have new Docker tags in order to specify which version of Ubuntu you want to use.

Monthly snapshots - These are the recommended Docker tags to use for the base image as they are very stable. These tags are created once a month as a snapshot of the image and don’t really change. So if you’re using an existing monthly snapshot, nothing will change on you. This applies to future snapshots. You can use the Ubuntu 18.04 or Ubuntu 20.04 versions of the monthly snapshot by using YYYY.MM-18.04 or YYYY.MM-20.04 tags respectively. This starts with the July snapshot meaning the snapshot images available with this tagging scheme are:


Stable tag - The stable tag points to the most recent monthly snapshot. Today, the stable tag would point to the 2020.07 tag while next month, it will point to the 2020.08 tag. Similar to monthly snapshots, you can use the Ubuntu 18.04 or Ubuntu 20.04 versions of the stable tag by appending the Ubuntu version to the tag:


Edge tag - The edge tag is more volatile than the others. It represents what’s in the master branch for the CircleCI Base Image repository. Again, just like monthly snapshots and the stable tag, you can use the Ubuntu 18.04 or Ubuntu 20.04 versions of the edge tag by appending the Ubuntu version to the tag:


Default Ubuntu Version - If you use a monthly snapshot, stable, or edge tag without a version specified, you will get our default Ubuntu version. Right now, the default version is Ubuntu 18.04. Starting with the September snapshot, the default Ubuntu version for the CircleCI Base image will switch to Ubuntu 20.04.

This means, if you want to start using Ubuntu 20.04 now, you can use the -20.04 suffix. If, by September, you don’t want to be forced to switch to Ubuntu 20.04, you can start using the -18.04 suffix today. Here’s a table showing what Ubuntu versions several tags would contain now, in August, and in September:

Tag Today, July 8th, 2020 August 2nd, 2020 September 2nd, 2020
cimg/base:stable Ubuntu 18.04 Ubuntu 18.04 Ubuntu 20.04
cimg/base:stable-18.04 Ubuntu 18.04 Ubuntu 18.04 Ubuntu 18.04
cimg/base:stable-20.04 Ubuntu 20.04 Ubuntu 20.04 Ubuntu 20.04
cimg/base:2020.07 Ubuntu 18.04 Ubuntu 18.04 Ubuntu 18.04
cimg/base:2020.07-18.04 Ubuntu 18.04 Ubuntu 18.04 Ubuntu 18.04
cimg/base:2020.07-20.04 Ubuntu 20.04 Ubuntu 20.04 Ubuntu 20.04
cimg/base:2020.09 n/a n/a Ubuntu 20.04
cimg/base:2020.09-18.04 n/a n/a Ubuntu 18.04
cimg/base:2020.09-20.04 n/a n/a Ubuntu 20.04

Language Images

Language images are images such as cimg/go, cimg/node, cimg/rust, cimg/ruby, etc. These images all are based on the CircleCI Base image and so all contain Ubuntu 18.04 today. Since we don’t overwrite full SemVer tags for language images, any existing tag will continue to contain Ubuntu 18.04. Starting in September, new tags created for these images will contain Ubuntu 20.04.

To explain how this works, let’s use the Go image as an example. Right now, to use Go v1.14.4 in CircleCI, you might use the Go Convenience Image with the corresponding tag. It would look like this: cimg/go:1.14.4. This image contains Ubuntu 18.04. Since we don’t override existing full SemVer tags, this image will always contain Ubuntu 18.04.

Let’s say that in August, when Go v1.15 comes out, we now have a new image tag, cimg/go:1.15. Since it isn’t September yet, this image too will and always will contain Ubuntu 18.04. Now let’s say the Go Team releases Go v1.14.5 and v1.15.1 on September 15th. The new tags, cimg/go:1.14.5 and cimg/go:1.15.1 were created after September 2nd so they will, and always will, contain Ubuntu 20.04.

To summarize, if you are using a language image, the change in CircleCI’s default version of Ubuntu for Convenience Images will only affect you if you choose to use a newer image tag, one that was created September 2nd or after. If you stick with an image such as cimg/node:14.0.0, there will be no change for you.


Ubuntu 20.04 is now available in some CircleCI Base image tags. Language images will only get this new Ubuntu version for tags created on or after September 2nd, 2020. None of this applies to legacy Convenience Images (images with the circleci/* namespace).