Docs
circleci.com
Start Building for Free

Using the macOS execution environment

yesterday6 min read
Cloud
On This Page

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 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:

jobs:
  build:
    macos:
      xcode: 13.4.1

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

Supported Xcode versions

ConfigXcode VersionmacOS VersionVM Software ManifestBare Metal Software ManifestRelease Notes
14.0.0Xcode 14 Beta 5 (14A5294e)12.4 Installed softwareN/A Release Notes
13.4.1Xcode 13.4 (13F17a)12.3.1 Installed software Installed software Release Notes
13.3.1Xcode 13.3 (13E500a)12.3.1 Installed software Installed software Release Notes
13.2.1Xcode 13.2.1 (13C100)11.6.2 Installed software Installed software Release Notes
13.1.0Xcode 13.1 (13A1030d)11.6.1 Installed software Installed software Release Notes
13.0.0Xcode 13.0 (13A233)11.5.2 Installed software Installed software Release Notes
12.5.1Xcode 12.5.1 (12E507)11.4.0 Installed software Installed software Release Notes
11.7.0Xcode 11.7 (11E801a)10.15.5 Installed software Installed software Release Notes

Available resource classes

ClassvCPUsRAM
medium4 @ 2.7 GHz8GB
macos.x86.medium.gen24 @ 3.2 GHz8GB
large8 @ 2.7 GHz16GB
macos.x86.metal.gen112 @ 3.2 GHz32GB
jobs:
  build:
    macos:
      xcode: 13.4.1
    resource_class: large

macOS VM storage

The amount of available storage on CircleCI macOS virtual machines depends on the resource class and Xcode image being used. The size of the Xcode images varies based on which tools are pre-installed. The table below indicates how much storage will be available with various Xcode/resource class combinations. Also note the exceptions to this noted below.

Xcode VersionClassMinimum Available Storage
10.3.0medium, large36GB
10.3.0macos.x86.medium.gen236GB
11.*medium, large23GB
11.*macos.x86.medium.gen223GB
12.*medium, large30GB
12.*macos.x86.medium.gen230GB
13.*medium, large23GB
13.*macos.x86.medium.gen289GB

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.

Periodically, CircleCI will update the version of macOS each image includes to ensure the execution environment is as up to date as possible. When a new major version of macOS is released, CircleCI will update once the new major version of Xcode reaches the xx.2 release. This ensures the execution environment is kept stable.

CircleCI will announce the availability of new macOS containers, including Xcode betas, in the announcements section of our Discuss site.

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 (which are frozen and will not change), once a new beta image is released it will overwrite the previous beta image 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, you should 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, please check out the following support center article.

Apple silicon support

It is 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.

Running or testing Apple Silicon apps natively is currently not possible as CircleCI build hosts are Intel-based Macs. Binaries will need to be exported as artifacts for testing apps locally. Alternatively, CircleCI runner can also be used to run jobs natively on Apple Silicon.

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. This 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:

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:

lipo -info circleci-demo-macos-x86_64

Which will output the following:

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 simply 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:

orbs:
  macos: circleci/macos@2

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

steps:
  - macos/preboot-simulator:
      version: "15.0"
      platform: "iOS"
      device: "iPhone 13 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:

steps:
  - macos/preboot-paired-simulator:
      iphone-device: "iPhone 13"
      iphone-version: "15.0"
      watch-device: "Apple Watch Series 7 - 45mm"
      watch-version: "8.0"

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 report is useful for diagnosing the exact cause of the crash. Crash reports can be uploaded as artifacts, as follows:

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.

Optimizing Cocoapods

In addition to the basic setup steps, it is best practice to use Cocoapods 1.8 or newer which allows the use of the CDN, rather than having to clone the entire Specs repo. This will allow you to install pods faster, reducing build times. If you are using Cocoapods 1.7 or older, consider upgrading to 1.8 or newer as this change allows for much faster job execution of the pod install step.

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

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:

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

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

sudo gem install cocoapods

A further recommendation is to check your Pods directory into source control. This will ensure that you have a deterministic, reproducible build.

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:

version: 2.1
jobs:
  build-and-test:
    macos:
      xcode: 12.5.1
    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:

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, please see our demo React Native application

Using Multiple Executor Types (macOS + Docker)

It is possible to use multiple executor types 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.

version: 2.1
jobs:
  build-and-test:
    macos:
      xcode: 13.4.1
    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 8
            SCAN_SCHEME: WebTests

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

  deploy-snapshot:
    docker:
      - image: cimg/deploy:2022.08
        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

Next steps

Get started with Configuring a Simple macOS Application on CircleCI.


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.

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.