--- title: "CircleCI Xcode image release, update, and deprecation policy" description: "Read the CircleCI policy for releasing, retaining, patching, and deprecating Xcode images, including beta image support and macOS versions." 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). # CircleCI Xcode image release, update, and deprecation policy **Cloud plans:** Free, Performance, Scale **Version control:** [All supported providers](https://circleci.com/docs/guides/integration/version-control-system-integration-overview/) ## Overview This document outlines the CircleCI Xcode image release, update, and deprecation policy. A defined Xcode image policy allows us to continue releasing new images, including beta images. You can find the most up-to-date information on these images on the [CircleCI Developer Hub](https://circleci.com/developer/machine/image/xcode) Xcode machine image page. ## Xcode image retention and deprecation We support the three latest Xcode versions released. We also support the latest minor release of the last four major Xcode versions. For example, if Xcode 27 is the latest major version: Xcode retention policy example | Xcode Version | Action | | --- | --- | | Xcode 27 | We retain the three latest `major.minor` versions at the latest patch version | | Xcode 26 | We retain the latest `major.minor` version | | Xcode 16 | We retain the latest `major.minor` version | | Xcode 15 | We retain the latest `major.minor` version | | Xcode 14 | We flag this version for deprecation and remove it 30 days after we announce the deprecation | Apple ships betas of new major versions of Xcode during WWDC, which occurs in June each year. ### Deprecation notice and retention period Once we select an Xcode image for deprecation, we retain it for 30 days before we remove it. We announce the deprecation through the following channels: * The [CircleCI changelog](https://circleci.com/changelog/). * An in-app banner, shown to the organizations and jobs affected by the deprecation. We never automatically redirect requests for specific Xcode images to a different major or minor version. When we remove an image, jobs using that image fail if you have not updated your CircleCI configuration file. ### Brownouts During the 30-day retention period, we schedule brownouts. A brownout is a temporary, planned period when we make a deprecated image unavailable on purpose. Jobs that use the image fail during a brownout. This warns you before we remove the image for good. For more information about how brownouts work and how to respond to them, see the [Image Brownouts](https://circleci.com/docs/guides/execute/machine-convenience-image-lifecycle/#image-brownouts) section of the image lifecycle page. ## Xcode patches We retain the latest patch version of each Xcode `major.minor` version we support. Once Apple releases a patch version, we deprecate the previous patch version and automatically redirect all requests to the updated patch of the same `major.minor` version. Patches are generally backwards compatible, so we put redirects in place within 24 hours of a patch release. If we discover any major issues, we retain the ability to issue a rollback and make both versions temporarily available. **Example:** When Apple released Xcode `13.2.1`, we removed the previous patch version, `13.2.0`, and automatically redirected all requests for `13.2.0` to `13.2.1`. ## Beta image support We aim to make beta Xcode versions available on the macOS executor at the earliest opportunity. This allows developers to test their apps ahead of the next stable Xcode release. Unlike our stable images (which we freeze once released), when we release a beta image it overwrites the previous beta image until we release an RC/Stable image. At that point we freeze the image and no longer update it. If you request an image using an Xcode version currently in beta, it changes when Apple releases a subsequent Xcode beta with minimal notice. This can include breaking changes in Xcode and associated tooling which are beyond our control. We do not recommend beta images for production pipelines. To read about our customer support policy for beta images, check out this [support center article](https://support.circleci.com/hc/en-us/articles/360046930351-What-is-CircleCI-s-Xcode-Beta-Image-Support-Policy-). ## Xcode image releases CircleCI commits to providing Xcode image updates within **2 business days** of Apple’s official GA release, as announced on [Apple’s official RSS feed](https://developer.apple.com/news/releases/rss/releases.rss). This commitment applies to stable, generally available Xcode releases only. We announce all images on our [changelog](https://circleci.com/changelog/) along with release notes. We also add them to the table of [Xcode Versions in the Documentation](https://circleci.com/docs/guides/execute/using-macos/#supported-xcode-versions). ### Exceptions to the release window #### Pre-release builds Beta releases and release candidates are not subject to the 2 business day commitment. We publish Beta and RC images on a best-effort basis with no guaranteed timeline. See [Beta image support](#beta-image-support) for more detail. #### macOS upgrade required For major Xcode releases that require a corresponding macOS upgrade on our fleet, the standard 2 business day window does not apply. We aim to publish a projected availability date within **5 business days** of Apple’s GA release. We post a notice on our [changelog](https://circleci.com/changelog/) when the image goes live. #### Image quality hold In rare cases, CircleCI’s validation process may identify critical issues with a newly released Xcode image. Examples include: * Toolchain regressions. * Simulator instability. * Build system defects introduced by Apple. When this occurs, we may delay availability beyond the standard window. We aim to post a notice on our [changelog](https://circleci.com/changelog/) within the original 2 business day window. The notice states that the release is under a quality hold. It also states whether Apple or CircleCI caused the issue. Once we know the scope of the fix, we share a projected timeline. ## macOS versions We build each Xcode image on top of a clean macOS install. We aim to keep the macOS version reasonably up to date with the latest version available. Generally our images can be up to 2 minor/patch versions behind the latest stable version. We aim to keep the macOS version aligned across our different macOS executors. Note that this may not always be the case. Check the [Software Manifest](https://circleci.com/docs/guides/test/testing-ios/#supported-xcode-versions) file for the image for the most accurate information. When Apple releases a new major version of macOS (ex: `27.0`), we start to use this version after at least two minor Xcode releases have passed. ## Exceptions At any time, we reserve the right to work outside of the information in this document if the circumstances require. When we need to make an exception to the policy, we aim to provide as much notice and clarity as possible. In these cases, we post an announcement on our [changelog](https://circleci.com/changelog/).