--- title: "Execution environments overview" description: "Compare the CircleCI execution environments: Docker, Linux VM, macOS, Windows, GPU, and Arm VM, and learn how images and resource classes apply." platform: "Cloud, Server" doc_version: "unversioned" last_updated: "2026-10-15" cloud_plans: "Free, Performance, Scale" version_control: "All supported providers" --- > For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md). > > For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt). # Execution environments overview **Cloud plans:** Free, Performance, Scale **Version control:** [All supported providers](https://circleci.com/docs/guides/integration/version-control-system-integration-overview/) CircleCI offers several execution environments: * Docker (x86 or Arm) * Linux VM (virtual machine) * macOS * Windows * GPU * Arm VM Each job defined in your project configuration is run in a separate execution environment, either a Docker container or a virtual machine. ## 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](https://circleci.com/docs/reference/configuration-reference/). ### 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](https://circleci.com/docs/guides/execute/circleci-images/) (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](https://circleci.com/docs/reference/configuration-reference/#available-linux-machine-images-cloud). * Jobs that require a macOS VM image (`macos`) may use an Xcode version. A full list is available on the [Using macOS](https://circleci.com/docs/guides/execute/using-macos/#supported-xcode-versions) 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](https://circleci.com/docs/guides/execute/resource-class-overview/) page. * For an overview of available resource classes per Plan, see the [Pricing page](https://circleci.com/pricing/). ## Docker **Legacy images with the prefix "CircleCI/" are [deprecated](https://discuss.circleci.com/t/legacy-convenience-image-deprecation/41034)** on December 31, 2021. For faster builds, upgrade your projects with [next-generation convenience images](https://circleci.com/blog/announcing-our-next-generation-convenience-images-smaller-faster-more-deterministic/). 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](https://circleci.com/developer/images?imageType=docker). ```yml 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](https://circleci.com/docs/guides/execute/using-docker/) page. ## Linux VM 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](https://circleci.com/developer/images?imageType=machine). ```yml jobs: build: # name of your job machine: # executor type image: ubuntu-2404:current steps: # Commands run in a Linux virtual machine environment ``` ```yml jobs: build: # name of your job machine: true # executor type steps: # Commands run in a Linux virtual machine environment ``` Find out more about the Linux VM execution environment on the [Using Linux Virtual Machines](https://circleci.com/docs/guides/execute/using-linuxvm/) 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](https://circleci.com/developer/machine/image/macos). If you want to run a macOS build on CircleCI Server, you will need to use [Self-hosted Runner](https://circleci.com/docs/runner/runner-overview/). ```yml jobs: build: # name of your job macos: # executor type xcode: 27.0.0 steps: # Commands run in a macOS virtual machine environment # with Xcode 27.0.0 installed ``` Find out more about the macOS execution environment on the [Using macOS](https://circleci.com/docs/guides/execute/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](https://circleci.com/developer/images?imageType=machine). ```yml version: 2.1 orbs: win: circleci/windows@4.1.1 # The Windows orb gives you everything you need to start using the Windows executor jobs: build: # name of your job executor: win/server-2022 # use one of the executors defined within the windows orb steps: # Commands are run in a Windows virtual machine environment - checkout - run: Write-Host 'Hello, Windows' ``` ```yaml version: 2.1 jobs: build: # name of your job resource_class: 'windows.medium' machine: image: 'windows-server-2022-gui:current' shell: 'powershell.exe -ExecutionPolicy Bypass' steps: # Commands are run in a Windows virtual machine environment - checkout - run: Write-Host 'Hello, Windows' ``` ```yml version: 2.1 jobs: build: # name of your job machine: image: windows-default steps: # Commands are run in a Windows virtual machine environment - checkout - run: Write-Host 'Hello, Windows' ``` Find out more about the Windows execution environment on the [Using the Windows Execution Environment](https://circleci.com/docs/guides/execute/using-windows/) page. See [the Windows orb page on the developer hub](https://circleci.com/developer/orbs/orb/circleci/windows) 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](https://circleci.com/developer/images?imageType=machine). It is not possible to run a GPU build on CircleCI Server. ```yml version: 2.1 jobs: build: machine: image: linux-cuda-12:default resource_class: gpu.nvidia.medium steps: - run: nvidia-smi ``` ```yml version: 2.1 jobs: build: machine: image: windows-server-2019-cuda resource_class: gpu.nvidia.small steps: - run: nvidia-smi ``` ```yml version: 2.1 orbs: win: circleci/windows@4.1.1 jobs: build: executor: win/server-2019-cuda steps: - run: 'Write-Host ''Hello, Windows''' ``` Find out more about the GPU execution environment on the [Using the GPU Execution Environment](https://circleci.com/docs/guides/execute/using-gpu/) 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](https://circleci.com/developer/images?imageType=machine). ```yml # .circleci/config.yml version: 2.1 jobs: build-medium: machine: image: ubuntu-2404:current resource_class: arm.medium steps: - run: uname -a - run: echo "Hello, Arm!" build-large: machine: image: ubuntu-2404:current resource_class: arm.large steps: - run: uname -a - run: echo "Hello, Arm!" workflows: build: jobs: - build-medium - build-large ``` ```yml # .circleci/config.yml version: 2.1 jobs: build-medium: machine: image: arm-default resource_class: arm.medium steps: - run: uname -a - run: echo "Hello, Arm!" build-large: machine: image: arm-default resource_class: arm.large steps: - run: uname -a - run: echo "Hello, Arm!" workflows: build: jobs: - build-medium - build-large ``` Find out more about the Arm VM execution environment on the [Using the Arm VM Execution Environment](https://circleci.com/docs/guides/execute/using-arm/) page. You can also use [Arm on Docker](https://circleci.com/docs/guides/execute/using-docker/#arm). ## Self-hosted runner CircleCI provides the ability to have self-hosted runners: * [Container Runner](https://circleci.com/docs/runner/container-runner/) using Kubernetes. * [Machine Runner](https://circleci.com/docs/runner/runner-overview/#machine-runner-use-case) using Linux, Windows, and macOS virtual machines. ## Port ranges When using a machine executor, if a port range is hard coded, avoid the range in `/proc/sys/net/ipv4/ip_local_reserved_ports`. 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. ## Next steps * Read more about [Pre-built CircleCI Convenience Images](https://circleci.com/docs/guides/execute/circleci-images/) for the Docker execution environment.