---
title: "Using the macOS execution environment"
description: "\"Learn how to configure a your jobs to run in the macOS execution environment.\""
platform: "Cloud"
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).

# Using the macOS execution environment

**Cloud plans:** Free, Performance, Scale

**Version control:** [All supported providers](https://circleci.com/docs/guides/integration/version-control-system-integration-overview/)

The macOS execution environment is used for iOS and macOS development, allowing you to test, build, and deploy macOS and iOS applications on CircleCI. The macOS executor runs jobs in a macOS environment and provides access to iPhone, iPad, Apple Watch, and Apple TV simulators.

You can use the macOS execution environment to run your [Jobs](https://circleci.com/docs/guides/orchestrate/jobs-steps/) in a macOS environment on a virtual machine (VM). You can access the macOS execution environment by using the `macos` executor and specifying an Xcode version:

```yaml
jobs:
  build:
    macos:
      xcode: 27.0.0
    resource_class: m4pro.medium

    steps:
      # Commands will execute in macOS container
      # with Xcode 27.0.0 installed
      - run: xcodebuild -version
```

## Supported Xcode versions

### Supported Xcode versions for Apple silicon

<table><thead><tr><th>Config</th><th>Xcode Version</th><th>macOS Version</th><th>Supported Resource Classes</th><th>VM Software Manifest</th><th>Release Notes</th><th>Other Notes</th></tr></thead><tbody><tr><td><code>27.2</code></td><td>Xcode 27.2 (27B5028f)</td><td>26.6.2</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v19652/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-27-2-beta-2-available/">Release Notes</a></td><td>-</td></tr><tr><td><code>27.1</code></td><td>Xcode 27.1 (27A9275)</td><td>26.6.2</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v19712/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-27-1-available/">Release Notes</a></td><td>-</td></tr><tr><td><code>27.0</code></td><td>Xcode 27.0 (27A266a)</td><td>26.6.2</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v19446/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-27-0-available/">Release Notes</a></td><td>-</td></tr><tr><td><code>26.6</code></td><td>Xcode 26.6 (17F113)</td><td>26.5.1</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v18807/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-26-6-available/">Release Notes</a></td><td>-</td></tr><tr><td><code>26.5</code></td><td>Xcode 26.5 (17F42)</td><td>26.3.1</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v18380/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-26-5-available/">Release Notes</a></td><td>-</td></tr><tr><td><code>26.4.1</code></td><td>Xcode 26.4.1 (17E202)</td><td>26.3</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v17723/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-26-4-1-available/">Release Notes</a></td><td>-</td></tr><tr><td><code>26.3.0</code></td><td>Xcode 26.3.0 (17C529)</td><td>15.6</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v16344/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-26-3-0-available/">Release Notes</a></td><td><a href="https://circleci.com/changelog/deprecation-of-xcode-14-3-1-26-3-0-26-2-0-and-26-1-1/">Deprecated October 30th, 2026</a></td></tr><tr><td><code>26.2.0</code></td><td>Xcode 26.2.0 (17C52)</td><td>15.6</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v15949/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-26-2-0-gm-available/">Release Notes</a></td><td><a href="https://circleci.com/changelog/deprecation-of-xcode-14-3-1-26-3-0-26-2-0-and-26-1-1/">Deprecated October 30th, 2026</a></td></tr><tr><td><code>26.1.1</code></td><td>Xcode 26.1.1 (17B100)</td><td>15.6</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v15895/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-26-1-1-available/">Release Notes</a></td><td><a href="https://circleci.com/changelog/deprecation-of-xcode-14-3-1-26-3-0-26-2-0-and-26-1-1/">Deprecated October 30th, 2026</a></td></tr><tr><td><code>16.4.0</code></td><td>Xcode 16.4 (16F6)</td><td>15.3.2</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v15338/manifest.txt">Installed software</a></td><td><a href="https://circleci.com/changelog/xcode-16-4-ga-available/">Release Notes</a></td><td>-</td></tr><tr><td><code>15.4.0</code></td><td>Xcode 15.4 (15F31d)</td><td>14.3.1</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v14775/manifest.txt">Installed software</a></td><td><a href="https://discuss.circleci.com/t/xcode-15-4-0-ga-released/50897">Release Notes</a></td><td>-</td></tr><tr><td><code>14.3.1</code></td><td>Xcode 14.3.1 (14E300b)</td><td>13.2.1</td><td><div><div><p><code>m4pro.medium</code><br><code>m4pro.large</code></p></div></div></td><td><a href="https://circle-macos-docs.s3.amazonaws.com/image-manifest/v12128/manifest.txt">Installed software</a></td><td><a href="https://discuss.circleci.com/t/xcode-14-3-1-rc-released/48152">Release Notes</a></td><td><a href="https://circleci.com/changelog/deprecation-of-xcode-14-3-1-26-3-0-26-2-0-and-26-1-1/">Deprecated October 30th, 2026</a></td></tr></tbody></table>

## Available resource classes

| Class | vCPUs | RAM | Cloud | Server |
| --- | --- | --- | --- | --- |
| `m4pro.medium` | 6 @ 4.51 GHz | 28GB | **Yes** | **No** |
| `m4pro.large` | 12 @ 4.51 GHz | 56GB | **Yes** | **No** |

```yaml
jobs:
  build:
    macos:
      xcode: 27.0.0
    resource_class: m4pro.medium
```

### View resource usage

To view the compute resource usage for the duration of a job in the CircleCI web app:

1.  In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage.
    
2.  Select **Pipelines** from the sidebar and locate your pipeline from the list. You can use the project, branch, date, and status search options to help.
    
3.  Select the job you want to access by selecting the job name.
    
4.  Select the **Resources** tab to view CPU and RAM usage for the duration of the job.
    

You can use these insights to decide whether to make changes to the job’s configured resource class.

> **Image:** Resources tab

Figure 1. Resources tab in web app for a job

## Image update cycle for the macOS executor

Each `macos` job is run in a fresh virtual machine, using a specified version of macOS. CircleCI builds and deploys a new image each time a new stable, or beta, version of Xcode is released by Apple. The contents of build images remain unchanged in most circumstances. However, in exceptional circumstances CircleCI might be forced to re-build a container. CircleCI’s goal is to keep your execution environment stable, and to allow you to opt-in to newer macOS environments by setting the `xcode` key in your `.circleci/config.yml` file.

CircleCI will announce the availability of new macOS images, including Xcode betas, on our [changelog](https://circleci.com/changelog).

### Beta image support

CircleCI aims to make beta Xcode versions available on the macOS executor as soon as possible to allow developers to test their apps ahead of the next stable Xcode release.

Unlike CircleCI’s stable images, beta images are not frozen. Each new beta release overwrites the previous one until a GM (stable) image is released, at which point the image is frozen and no longer updated.

If you are requesting an image using an Xcode version that is currently in beta, expect it to change when Apple releases a new Xcode beta with minimal notice. This can include breaking changes in Xcode and associated tooling, which are beyond CircleCI’s control.

To read about CircleCI’s customer support policy regarding beta images, check out the following [support center article](https://support.circleci.com/hc/en-us/articles/360046930351-What-is-CircleCI-s-Xcode-Beta-Image-Support-Policy-).

### Apple silicon support

Running or testing Apple silicon apps natively can be done on our silicon-based Macs or by using [CircleCI Runner](https://circleci.com/docs/runner/runner-overview/#available-self-hosted-runner-platforms).

It is also possible to build Apple silicon/universal binaries using Xcode `12.0.0` and higher, as Apple provides both the Intel (`x86_64`) and Apple silicon (`arm64`) toolchains in this release. Cross-compiling Apple silicon binaries on Intel hosts has an additional overhead, and, as a result, compilation times will be longer than native compilation for Intel.

## Xcode cross compilation

### Universal binaries

Xcode currently supports the creation of universal binaries which can be run on both `x86_64` and `ARM64` CPU architectures without needing to ship separate executables. Universal binary support is supported only under Xcode `12.2`+, although older Xcode versions can still be used to compile separate `x86_64` and `ARM64` executables.

### Extract unwanted architectures

By default, Xcode `12.2`\+ will create universal binaries, compiling to a single executable that supports both `x86_64` and `ARM64` based CPUs. If you need to remove an instruction set, you can do so by using the `lipo` utility.

Assuming that you want to create a standalone `x86_64` binary from a universal binary called `circleci-demo-macos`, you can do so by running the command:

```shell
lipo -extract x86_64 circleci-demo-macos.app/Contents/MacOS/circleci-demo-macos -output circleci-demo-macos-x86_64
```

You can then confirm the supported architecture of the extracted binary with the following:

```shell
lipo -info circleci-demo-macos-x86_64
```

Which will output the following:

```shell
Architectures in the fat file: circleci-demo-macos-x86_64 are: x86_64
```

### Cross compiled binaries

While universal binaries are only supported under Xcode `12.2`+, you can still cross compile binaries for architectures other than the architecture of the machine being used to build the binary. For `xcodebuild` the process is relatively straightforward. To build `ARM64` binaries, prepend the `xcodebuild` command with `ARCHS=ARM64 ONLY_ACTIVE_ARCH=NO` such that it reads `xcodebuild ARCHS=ARM64 ONLY_ACTIVE_ARCH=NO`. For the `x86_64` architecture change `ARCHS` to `x86_64`.

## Optimization and best practices

### Pre-start the simulator

Pre-start the iOS simulator before building your application to make sure that the simulator is booted in time. Doing so generally reduces the number of simulator timeouts observed in builds.

To pre-start the simulator, add the macOS orb (version `2.0.0` or higher) to your config:

```yaml
orbs:
  macos: circleci/macos@2.5.4
```

Then call the `preboot-simulator` command, as shown in the example below:

```yaml
steps:
  - macos/preboot-simulator:
      version: "26.2"
      platform: "iOS"
      device: "iPhone 17 Pro Max"
```

It is advisable to place this command early in your job to allow maximum time for the simulator to boot in the background.

If you require an iPhone simulator that is paired with an Apple Watch simulator, use the `preboot-paired-simulator` command in the macOS orb:

```yaml
steps:
  - macos/preboot-paired-simulator:
      iphone-device: "iPhone 17"
      iphone-version: "26.2"
      watch-device: "Apple Watch Series 11 - 46mm"
      watch-version: "26.2"
```

It may take a few minutes to boot a simulator, or longer if booting a pair of simulators. During this time, any calls to commands such as `xcrun simctl list` may appear to hang while the simulator is booting up.

### Collecting iOS simulator crash reports

Often if your `scan` step fails, for example, due to a test runner timeout, it is likely that your app has crashed during the test run. In such cases, collecting crash reports is useful for diagnosing the exact cause of the crash. Crash reports can be uploaded as artifacts, as follows:

```yaml
steps:
  # ...
  - store_artifacts:
    path: ~/Library/Logs/DiagnosticReports
```

### Optimizing Fastlane

By default, Fastlane Scan generates test output reports in `html` and `junit` formats. If your tests are taking a long time and you do not need these reports, consider disabling them by altering the `output_type` parameter as described in the [Fastlane docs](https://docs.fastlane.tools/actions/run_tests/#parameters).

### Optimizing CocoaPods

In addition to the steps above, it is best practice to use a current version of CocoaPods which supports the CDN, rather than having to clone the entire Specs repository. This will allow you to install pods faster, reducing build times. The current macOS image ships with CocoaPods `1.16.2`. If you are using CocoaPods 1.7 or older, upgrade to take advantage of CDN support and faster `pod install` execution.

To enable this, ensure the first line in your Podfile is as follows:

```shell
source 'https://cdn.cocoapods.org/'
```

If upgrading from CocoaPods 1.7 or older, ensure the **Fetch CocoaPods Specs** step is removed from your CircleCI configuration, and ensure the following line is removed from your Podfile:

```shell
source 'https://github.com/CocoaPods/Specs.git'
```

To update CocoaPods to the latest stable version, update the Ruby gem with the following command:

```shell
sudo gem install cocoapods
```

A further recommendation is to check your [Pods directory into source control](https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control). This will ensure that you have a deterministic, reproducible build.

The previous S3 mirror provided by CircleCI for the CocoaPods Spec repository is no longer being maintained or updated since the release of CocoaPods 1.8. It will remain available to prevent existing jobs breaking, however, switching to the CDN method described above is recommended.

### Optimizing Homebrew

Homebrew, by default, will check for updates at the start of any operation. As Homebrew has a fairly frequent release cycle, this means that any step which calls `brew` can take some extra time to complete.

If build speed, or bugs introduced by new Homebrew updates are a concern, this automatic update feature can be disabled. On average, this can save up to two to five minutes per job.

To disable this feature, define the `HOMEBREW_NO_AUTO_UPDATE` environment variable within your job:

```yaml
version: 2.1
jobs:
  build-and-test:
    macos:
      xcode: 27.0.0
    environment:
      HOMEBREW_NO_AUTO_UPDATE: 1
    steps:
      - checkout
      - run: brew install wget
```

## Supported build and test tools

With the macOS executor on CircleCI, it is possible to customize your build as needed to satisfy almost any iOS build and test strategy.

### Common test tools

The following common test tools are known to work well on CircleCI:

*   [XCTest](https://developer.apple.com/library/ios/documentation/DeveloperTools/Conceptual/testing_with_xcode/chapters/01-introduction.html)
    
*   [Kiwi](https://github.com/kiwi-bdd/Kiwi)
    
*   [KIF](https://github.com/kif-framework/KIF)
    
*   [Appium](https://appium.io/)
    

### React Native projects

React Native projects can be built on CircleCI using `macos` and `docker` executor types. For an example of configuring a React Native project, see [our demo React Native application](https://github.com/CircleCI-Public/circleci-demo-react-native).

## Using multiple executor types (macOS + Docker)

It is possible to use multiple [Executor Types](https://circleci.com/docs/guides/execute/executor-intro/) in the same workflow. In the following example each push of an iOS project will be built on macOS, and a deploy image will run in Docker.

```yaml
version: 2.1
jobs:
  build-and-test:
    macos:
      xcode: 27.0.0
    environment:
      FL_OUTPUT_DIR: output

    steps:
      - checkout
      - run:
          name: Install CocoaPods
          command: pod install --verbose

      - run:
          name: Build and run tests
          command: fastlane scan
          environment:
            SCAN_DEVICE: iPhone 17
            SCAN_SCHEME: WebTests

      - store_test_results:
          path: output/scan
      - store_artifacts:
          path: output

  deploy-snapshot:
    docker:
      - image: cimg/deploy:2026.02
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - checkout
      - run: echo "Do the things"

workflows:
  build-test-lint:
    jobs:
      - deploy-snapshot
      - build-and-test
```

`cimg/deploy` is updated monthly. For the latest available tag, see [cimg/deploy on Docker Hub](https://hub.docker.com/r/cimg/deploy/tags).

## Next steps

Get started with [Configuring a Simple macOS Application on CircleCI](https://circleci.com/docs/guides/execute/hello-world-macos/).