Configuring Machine and macOS Executors

1. Specifying Machine Executor

Property	Values	Description
machine	`true` or `false`	Enables or disables the machine executor. Default is `false`.
image	`circleci/machine:default` or custom image	Specifies the machine image to use. Default is `circleci/machine:default`.
docker_layer_caching	`true` or `false`	Enables Docker layer caching. Default is `false`.

Example: Using Machine Executor

version: 2.1
jobs:
  build:
    machine: true
    image: circleci/machine:default
    steps:
      - checkout
      - run: echo "Running on machine executor"

2. Setting Machine Image Versions

Image Family	Version	Description	Notes
machine	`ubuntu-2204:2024.01.1`	Ubuntu 22.04 with latest updates	Default image for most projects
machine	`ubuntu-2004:2023.09.1`	Ubuntu 20.04 with latest updates	Legacy support, may be deprecated in future
machine	`macos-13:2024.01.1`	macOS 13 (Ventura) with latest updates	For projects requiring macOS environment
machine	`macos-12:2023.09.1`	macOS 12 (Monterey) with latest updates	Legacy macOS support, may be deprecated in future

Example: Setting Machine Image in Config

version: 2.1
jobs:
  build:
    machine:
      image: ubuntu-2204:2024.01.1
    steps:
      - checkout
      - run: echo "Running on Ubuntu 22.04"

Note: Image versions are updated regularly. Always check the CircleCI documentation for the latest stable image versions.

3. Using Linux Machine Images

Image	Description	Available Resources	Notes
circleci/linux-machine:20.04	Ubuntu 20.04 with pre-installed tools	4 vCPUs, 8 GB RAM, 50 GB SSD	Default image for Linux machine executors
circleci/linux-machine:22.04	Ubuntu 22.04 with latest packages	4 vCPUs, 8 GB RAM, 50 GB SSD	Recommended for newer projects
circleci/linux-machine:24.04	Ubuntu 24.04 with latest features	4 vCPUs, 8 GB RAM, 50 GB SSD	NEW - Latest LTS release

Example: Using Ubuntu 22.04 Image

version: 2.1
jobs:
  build:
    machine:
      image: circleci/linux-machine:22.04
    steps:
      - checkout
      - run:
          name: Check installed packages
          command: |
            echo "Node version:"
            node --version
            echo "Python version:"
            python3 --version

Note: The machine executor provides full virtualization, allowing access to system-level features and tools not available in containerized environments.

4. Specifying macOS Executor

Property	Values	Description
executor	`macos`	Specifies the macOS executor for the job
macos	`{version: '12.0'}`	Version of macOS to use (e.g., 12.0, 13.0)
xcode	`14.2.0`	Xcode version to use (e.g., 14.2.0, 15.0.0)

Example: macOS Executor Configuration

jobs:
  build:
    executor:
      name: macos
      version: '12.0'
    steps:
      - checkout
      - run:
          name: Run tests
          command: xcodebuild test

Note: The macOS executor runs on Apple Silicon or Intel-based Macs depending on the version specified.

5. Configuring macOS Xcode Versions

Xcode Version	macOS Version	Supported in CircleCI	Notes
15.4	`macOS 14 (Sonoma)`	NEW	Latest stable Xcode version as of 2026
15.2	`macOS 14 (Sonoma)`	Yes	Released in 2024
15.0	`macOS 14 (Sonoma)`	Yes	First release of Xcode 15
14.3	`macOS 13 (Ventura)`	Yes	Released in 2023
14.2	`macOS 13 (Ventura)`	Yes	Released in 2023
14.1	`macOS 13 (Ventura)`	Yes	Released in 2023
14.0	`macOS 13 (Ventura)`	Yes	First release of Xcode 14
13.4	`macOS 12 (Monterey)`	Yes	Released in 2023
13.3	`macOS 12 (Monterey)`	Yes	Released in 2023
13.2	`macOS 12 (Monterey)`	Yes	Released in 2023
13.1	`macOS 12 (Monterey)`	Yes	Released in 2023
13.0	`macOS 12 (Monterey)`	Yes	First release of Xcode 13

Example: Setting Xcode Version in CircleCI Config

version: 2.1
jobs:
  build:
    macos:
      xcode: "15.4"
    steps:
      - checkout
      - run: xcodebuild -version

Note: Ensure that the specified Xcode version is compatible with your project's deployment target and supported platforms.

6. Specifying Windows Executor

Property	Values	Description
executor	`windows`	Specifies the Windows executor for the job
windows.image	`circleci/windows-server:2019`	Base image for the Windows job environment

Example: Using Windows Executor

version: 2.1
jobs:
  build:
    executor:
      name: windows
      image: circleci/windows-server:2019
    steps:
      - checkout
      - run: echo "Hello from Windows"

Note: The Windows executor is only available in CircleCI Enterprise.

7. Using Windows Orb

Property	Description	Values
orbs	Defines the orb to use for Windows executor configuration	`circleci/windows@2.0`
executor	Specifies the Windows executor to use	`win/default`, `win/server-2019`

Example: Using Windows Orb

version: 2.1
orbs:
  win: circleci/windows@2.0
jobs:
  build:
    executor: win/default
    steps:
      - checkout
      - run: echo "Hello from Windows"

Note: The Windows orb requires a Windows executor and is only available in CircleCI's paid plans.

8. Choosing Between Docker and Machine

Comparison: Docker vs Machine Executors

Docker Executor: Runs jobs in isolated containers using Docker images. Ideal for lightweight, reproducible environments with fast startup times.
Machine Executor: Runs jobs on full Linux virtual machines with root access. Suitable for complex setups, custom configurations, or when Docker limitations are a concern.

Feature	Docker Executor	Machine Executor
Environment Type	Container-based	VM-based
Root Access	No	Yes
Startup Time	Fast (seconds)	Slower (minutes)
Customization	Limited to image configuration	Full control over OS and packages
Resource Usage	Lightweight	Heavier due to VM overhead
Network Access	Standard container networking	Full network access and configuration
Use Case	Standard builds, testing, CI/CD pipelines	Complex dependencies, legacy software, custom tools

Example: Docker Executor Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install

Example: Machine Executor Configuration

version: 2.1
jobs:
  build:
    machine:
      image: ubuntu-2004:202107-02
    steps:
      - checkout
      - run: sudo apt-get update

9. Configuring Resource Classes

Resource Class	CPUs	Memory	Notes
medium	`2`	`4GB`	Default for most builds
large	`4`	`8GB`	Good for CPU-intensive tasks
xlarge	`8`	`16GB`	For memory-heavy builds
2xlarge	`16`	`32GB`	High-performance builds
2xlarge+NEW	`32`	`64GB`	Latest high-performance option

Example: Setting Resource Class in Config

version: 2.1
jobs:
  build:
    machine:
      image: ubuntu-2004:202107-01
      resource_class: large
    steps:
      - checkout
      - run: echo "Running on large resource class"

Note: Resource classes are only available for machine and macos executors. They are not supported for docker or linux executors.

10. Using ARM Resources

Resource	Description	Availability
arm	ARM64 architecture support for builds	NEW Available in CircleCI Enterprise and Cloud
arm64	Explicitly request ARM64 architecture	NEW Supported in CircleCI Cloud v2.1+

Example: ARM64 Configuration

version: 2.1
jobs:
  build:
    machine:
      image: ubuntu-2004:2023.07.1
      resource_class: arm
    steps:
      - checkout
      - run: echo "Running on ARM64"

Note: ARM resources are currently in beta and may not be available in all regions.

Warning: Not all tools and dependencies are compatible with ARM64 architecture. Ensure your build environment supports ARM.