Execution environments overview

Cloud

Server v4.x

Executors

For each job in your project config you will specify an execution environment by assigning it an executor. An executor defines the underlying technology or environment in which to run a job, and which image to use to suit your job.

It is possible to specify a different executor and image for each job in your .configuration file.

Images, containers, and virtual machines

An image is a packaged system that has the instructions for creating a running environment.

A container or virtual machine is the term used for a running instance of an image.

For example:

Jobs that require Docker images (docker) may use an image for Node.js, Python etc. The pre-built CircleCI Docker image (convenience images) will help you get started. CircleCI convenience images are not a full operating system, so they generally make building your software more efficient.
Jobs that require a complete Linux virtual machine (VM) image (machine) may use an Ubuntu version supported by the list of available machine images.
Jobs that require a macOS VM image (macos) may use an Xcode version. A full list is available on the Using macOS page.

Resource class

When you configure an executor it is recommended that you also specify a resource class to specify compute resource size (CPU and RAM).

For an overview of resource classes, see the Resource class overview page.
For an overview of available resource classes per Plan, see the Pricing page.

Docker

Legacy images with the prefix "circleci/" were deprecated on December 31, 2021. For faster builds, upgrade your projects with next-generation convenience images.

To access the Docker execution environment, use the docker executor and specify an image. For a full list of convenience images, which are built by CircleCI, see the CircleCI Developer Hub

jobs:
  build: # name of your job
    docker: # executor type
      - image: cimg/base:stable # primary container will run the latest, production-ready base image

    steps:
        # Commands run in the primary container

Find out more about the Docker execution environment on the Using Docker page.

Linux VM

CircleCI cloud The use of machine: true is deprecated. You must specify an image to use.

To access the Linux VM execution environment, use the machine executor and specify a Linux image. For a full list of machine images, see the CircleCI Developer Hub

Find out more about the Linux VM execution environment in the Using Linux Virtual Machines page.

macOS

To access the macOS execution environment, use the macos executor and specify an image using the xcode key. For a full list of macOS images, see the CircleCI Developer Hub.

If you want to run a macOS build on CircleCI server, you will need to use self-hosted runner.

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

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

Find out more about the macOS execution environment on the Using macOS page.

Windows

To access the Windows execution environment, you can either:

Use the Windows orb and specify one of the default executors.
Use the machine executor and specify a Windows image.

For a full list of machine images, see the CircleCI Developer Hub.

Find out more about the Windows execution environment in the Using the Windows Execution Environment page. See the Windows orb page in the developer hub for the list of options available in the Windows orb.

GPU

To access the GPU execution environment, use one of the following:

The Windows orb and specify the GPU-enabled executor.
The machine executor and specify a Linux or Windows GPU-enabled image.

For a full list of machine images, see the CircleCI Developer Hub.

It is not possible to run a GPU build on CircleCI server.

Find out more about the GPU execution environment on the Using the GPU Execution Environment page.

Arm VM

To access the Arm VM execution environment, use the machine executor as detailed below, and specify either the arm.medium or the arm.large resource class. For a full list of machine images, see the CircleCI Developer Hub.

Find out more about the Arm VM execution environment in the Using the Arm VM Execution Environment page. You can also use Arm on Docker.

Self-hosted runner

CircleCI provides the ability to have self-hosted runners:

Container runner using Kubernetes.
Machine runner using Linux, Windows, and macOS virtual machines.

Port ranges

When using a machine executor, if a port range is hard coded, the range in /proc/sys/net/ipv4/ip_local_reserved_ports should be avoided. Port range 32768 - 60999 is used by the TCP stack to allocate ephemeral ports for connections. Ports in that range may have already been allocated by a previous connection, so collisions are possible.