Xcode cache

Tuist provides support for the Xcode compilation cache, which allows teams to share compilation artifacts by leveraging the build system’s caching capabilities.

The Xcode cache was introduced in Xcode 26. You might also see it referred to as the Xcode build cache; it reuses compilation artifacts keyed by their inputs, and Tuist’s remote cache makes those artifacts shareable across machines.

Setup

If you don’t already have a Tuist account and project, you can create one by running:

tuist init

Once you have a Tuist.swift file referencing your fullHandle, you can set up the caching for your project by running:

tuist setup cache

This command creates a LaunchAgent to run a local cache service on startup that the Swift build system uses to share compilation artifacts. This command needs to be run once in both your local and CI environments.

To set up the cache on the CI, make sure you are authenticated.

Configure Xcode Build Settings

Add the following build settings to your Xcode project:

COMPILATION_CACHE_ENABLE_CACHING = YES
COMPILATION_CACHE_REMOTE_SERVICE_PATH = $HOME/.local/state/tuist/your_org_your_project.sock
COMPILATION_CACHE_ENABLE_PLUGIN = YES
COMPILATION_CACHE_ENABLE_DIAGNOSTIC_REMARKS = YES

Note that COMPILATION_CACHE_REMOTE_SERVICE_PATH and COMPILATION_CACHE_ENABLE_PLUGIN need to be added as user-defined build settings since they’re not directly exposed in Xcode’s build settings UI:

You can also specify these settings when running xcodebuild by adding the following flags, such as:

xcodebuild build -project YourProject.xcodeproj -scheme YourScheme \
    COMPILATION_CACHE_ENABLE_CACHING=YES \
    COMPILATION_CACHE_REMOTE_SERVICE_PATH=$HOME/.local/state/tuist/your_org_your_project.sock \
    COMPILATION_CACHE_ENABLE_PLUGIN=YES \
    COMPILATION_CACHE_ENABLE_DIAGNOSTIC_REMARKS=YES

In that case, all you need is to add enableCaching: true to your Tuist.swift file:

import ProjectDescription

let tuist = Tuist(
    fullHandle: "your-org/your-project",
    project: .tuist(
        generationOptions: .options(
            enableCaching: true
        )
    )
)

Cache upload policy

By default, the cache service both downloads and uploads artifacts to the remote cache. You can control this with the cache option in your Tuist.swift file to enable read-only mode, where artifacts are downloaded but never uploaded:

import ProjectDescription

let tuist = Tuist(
    fullHandle: "your-org/your-project",
    cache: .cache(
        upload: false
    ),
    project: .tuist(
        generationOptions: .options(
            enableCaching: true
        )
    )
)

A common pattern is to push artifacts only from CI, where builds are reproducible, while keeping local environments read-only. You can achieve this using Environment.isCI, which checks for the CI environment variable set by most CI providers:

import ProjectDescription

let tuist = Tuist(
    fullHandle: "your-org/your-project",
    cache: .cache(
        upload: Environment.isCI
    ),
    project: .tuist(
        generationOptions: .options(
            enableCaching: true
        )
    )
)

With this setup, local builds benefit from cached artifacts without uploading, while CI builds populate the cache for the rest of the team.

Continuous integration

To enable caching in your CI environment, you need to run the same command as in local environments: tuist setup cache.

For authentication, you can use either OIDC authentication (recommended for supported CI providers) or an account token via the TUIST_TOKEN environment variable.

An example workflow for GitHub Actions using OIDC authentication:

name: Build

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v2
      - run: tuist auth login
      - run: tuist setup cache
      - # Your build steps

See the Continuous Integration guide for more examples, including token-based authentication and other CI platforms like Xcode Cloud, CircleCI, Bitrise, and Codemagic.