Migrating to next-gen Convenience Images
On This Page
In 2020 CircleCI introduced the next generation (next-gen) of convenience images. These new images are designed to replace the legacy convenience images that were released during the announcement of CircleCI 2.0. The next-gen CircleCI convenience images are designed from the ground up for a CI/CD environment. They are designed to be faster, more efficient, and most importantly, more reliable. You can learn more about all of the features on our blog post. As we begin to deprecate the legacy images, this document provides information on the migration process.
Moving from a legacy to next-gen image requires a change to the namespace. All legacy images have a Docker namespace of
circleci, while next-gen images have a Docker namespace of
cimg. For example, migrating from the legacy Ruby or Python image to the respective next-gen image can be done as follows:
- circleci/ruby:2.7.4 + cimg/ruby:2.7.4
- circleci/python:3.8.4 + cimg/python:3.8.4
Several changes are being made to existing images. The following images will be deprecated without next-gen equivalents:
If you are using the
buildpack-deps image, the suggestion is to use the new CircleCI Base image,
cimg/base. For the other two images, you can install the software yourself in the base image or use a 3rd-party image instead.
Also, the following image will be renamed:
- The Go image will be changed from
All Legacy to Next-Gen image changes are captured below in this table:
|Legacy Image||Next-Gen Image|
|circleci/jruby||No suggested path|
|circleci/dynamodb||No suggested path|
With legacy images, there were 4 different variant tags you could use to get browser testing for a particular image. For example, if you were doing browser testing with the Python v3.7.0 image, you might have used Docker image: circleci/python:3.7.0-browsers. These 4 tags have now been consolidated into a single tag designed to be used together with the CircleCI Browser Tools orb.
|Legacy variant tags||Next-gen variant tags|
The new, single browsers variant tag includes Node.js, common utilities to use in browser testing such as Selenium, but not the actual browsers. Please note the browsers are no longer pre-installed. Instead, browsers such as Google Chrome and Firefox, as well as their drivers Chromedriver and Gecko, are installed via the
browsers-tools orb. This provides the flexibility to mix and match the browser versions you need in a build rather than using strictly what CircleCI provides. You can find examples of how to use this orb here.
Using Ubuntu as the Single Base OS
Legacy images had variant tags for several different base operating systems. Some images were versions of Debian and Ubuntu, while other images provided several different bases. This is no longer the case. All CircleCI next-gen images are based on the latest LTS release of Ubuntu.
With the base image, at least two LTS releases and non-EOL’d standard releases will be supported.
When migrating to a next-gen image, there might be some software issues. Common issues include:
- A library you were using now has a different version.
- An apt package is no longer pre-installed. In this scenario simply install that package using:
sudo apt-get update && sudo apt-get install -y <the-package>
Each image has its own GitHub repository. You can find them here. These repositories are where you can learn more about an image, what makes up the image, open GitHub issues, and contribute PRs. If you are having an issue with an image, especially if it is a migration issue, you can open up a GitHub issue and ask questions. You can also open a support ticket or reach out on CircleCI Discuss.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guidefirst).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.