Executors and Images

CircleCI offers several build environments. We call these executors. An executor defines the underlying technology or environment in which to run a job. Set up your jobs to run in the docker, machine, macos or windows executor and specify an image with the tools and packages you need.

Executor Overview

Docker

jobs:
  build: # name of your job
    docker: # executor type
      - image: buildpack-deps:trusty # primary container will run Ubuntu Trusty

      steps:
        # Commands run in the primary container

Find out more about using the docker executor here.

Machine

jobs:
  build: # name of your job
    machine: # executor type
      image: ubuntu-2004:202010-01 # # recommended linux image - includes Ubuntu 20.04, docker 19.03.13, docker-compose 1.27.4

      steps:
        # Commands run in a Linux virtual machine environment

jobs:
  build:
    machine:
      image: ubuntu-1604:202007-01 # VM will run Ubuntu 16.04 for this release date
    steps:
      # Commands run in a Linux virtual machine environment

Find out more about using the machine executor here.

macOS

The macOS executor is not currently available on self-hosted installations of CircleCI Server

jobs:
  build: # name of your job
    macos: # executor type
      xcode: 11.3.0

    steps:
      # Commands run in a macOS virtual machine environment
      # with Xcode 11.3 installed

Find out more about using the macos executor here.

Windows

The syntax for using the Windows executor in your config differs depending on whether you are using:

The cloud version of CircleCI, using config version 2.1 and the Windows orb.
Self-hosted installation of CircleCI Server with config version 2.0 – this option is an instance of using the machine executor with a Windows image – Introduced in CircleCI Server v2.18.3.

version: 2.1 # Use version 2.1 to enable orb usage.

orbs:
  win: circleci/windows@2.2.0 # The Windows orb give you everything you need to start using the Windows executor.

jobs:
  build: # name of your job
    executor: win/default # executor type

    steps:
      # Commands are run in a Windows virtual machine environment
      - checkout
      - run: Write-Host 'Hello, Windows'

version: 2

jobs:
  build: # name of your job
    machine:
      image: windows-default # Windows machine image
    resource_class: windows.medium
    steps:
      # Commands are run in a Windows virtual machine environment
      - checkout
      - run: Write-Host 'Hello, Windows'

Find out more about using the windows executor here. See the Windows orb details for the list of options available in the Windows orb.

Learn More

Take the build environments course with CircleCI Academy to learn more about choosing and using an executor.

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 guide first).
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.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.