Executors and Images

2 months ago • 1 min read

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.

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 the docker executor in the Using Docker section of the Choosing an Executor Type page.

Machine

Ubuntu 14.04 and 16.04 machine images are deprecated and will be removed permanently May 31, 2022. These images will be temporarily unavailable March 29 and April 26, 2022. Migrate from 14.04 or 16.04.

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: true # executor type
    steps:
      # Commands run in a Linux virtual machine environment

jobs:
  build: # name of your job
    machine: true # executor type

    steps:
      # Commands run in a Linux virtual machine environment

Find out more about the machine executor in the Using machine section of the Choosing an Executor Type page.

macOS

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

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

Find out more about the macos executor in the Using macOS section of the Choosing an Executor Type page.

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: # executor type
      image: windows-default
    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: # executor type
      image: windows-default
    resource_class: windows.medium
    steps:
      # Commands are run in a Windows virtual machine environment
      - checkout
      - run: Write-Host 'Hello, Windows'

Find out more about the windows executor in the Using the Windows executor section of the Choosing an Executor Type page. See the Windows orb details for the list of options available in the Windows orb.

See also

• Choosing an executor type
• Pre-built CircleCI convenience images
• Building on MacOS
• Building on Windows

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.

Need support?

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.