# Xcode cache {#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 {#setup}

::: warning REQUIREMENTS
<!-- -->
- A <LocalizedLink href="/guides/server/accounts-and-projects">Tuist account and project</LocalizedLink>
- Xcode 26.0 or later
<!-- -->
:::

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

```bash
tuist init
```

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

```bash
tuist setup cache
```

This command creates a [LaunchAgent](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html) to run a local cache service on startup that the Swift [build system](https://github.com/swiftlang/swift-build) 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 <LocalizedLink href="/guides/integrations/continuous-integration#authentication">authenticated</LocalizedLink>.

### Configure Xcode Build Settings {#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:

::: info SOCKET PATH
<!-- -->
The socket path will be displayed when you run `tuist setup cache`. It's based on your project's full handle with slashes replaced by underscores.
<!-- -->
:::

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

::: info GENERATED PROJECTS
<!-- -->
Setting the settings manually is not needed if your project is generated by Tuist.

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

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

### Cache upload policy {#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:

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

```swift
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 {#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 <LocalizedLink href="/guides/server/authentication#oidc-tokens">OIDC authentication</LocalizedLink> (recommended for supported CI providers) or an <LocalizedLink href="/guides/server/authentication#account-tokens">account token</LocalizedLink> via the `TUIST_TOKEN` environment variable.

An example workflow for GitHub Actions using OIDC authentication:
```yaml
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 <LocalizedLink href="/guides/integrations/continuous-integration">Continuous Integration guide</LocalizedLink> for more examples, including token-based authentication and other CI platforms like Xcode Cloud, CircleCI, Bitrise, and Codemagic.