Skip to content
Docs
Cancel

Executors and Images

Last updated
Tags Cloud Server v2.x Server v3.x

CircleCI offers several execution 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: # name of your job
    machine: # executor type
      image: ubuntu-1604:202007-01 # VM will run Ubuntu 16.04 for this release date

    steps:
      # Commands run in a Linux virtual machine environment

jobs:
  build: # name of your job
    machine: # executor type
      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: 12.5.1

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

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'

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.

See also

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.

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