> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tuist/tuist/llms.txt
> Use this file to discover all available pages before exploring further.
# Cache
> Speed up builds with Tuist's binary caching service
Tuist Cache is a service that stores compiled binaries of your frameworks and targets in the cloud. When you or your team rebuild the project, Tuist fetches pre-built binaries instead of recompiling unchanged code, dramatically reducing build times.
## How It Works
The cache service works by:
1. **Hashing** each target based on its source files, dependencies, and build settings
2. **Checking** if a cached binary exists for that hash
3. **Downloading** the cached binary if available, or building and uploading if not
4. **Replacing** source targets with their cached binaries in your Xcode project
```mermaid theme={null}
graph LR
A[Source Code] --> B[Generate Hash]
B --> C{Cache Exists?}
C -->|Yes| D[Download Binary]
C -->|No| E[Build Target]
E --> F[Upload to Cache]
D --> G[Use Binary]
F --> G
```
## Prerequisites
Before using the cache:
1. [Authenticate with Tuist Cloud](/cloud/authentication)
2. Configure your project in `Config.swift`
```swift Config.swift theme={null}
import ProjectDescription
let config = Config(
cloud: .cloud(
url: "https://cloud.tuist.io",
projectId: "your-org/your-project"
),
cache: .cache(
// Cache configuration options
)
)
```
## Warming the Cache
The `tuist cache warm` command builds targets and uploads them to the cache:
```bash theme={null}
tuist cache warm
```
### Cache Specific Targets
Cache only specific targets and their dependencies:
```bash theme={null}
tuist cache warm MyFramework AnotherFramework
```
### Cache Only Dependencies
Cache dependencies without caching the specified targets:
```bash theme={null}
tuist cache warm MyApp --external-only
```
This is useful when you're actively developing `MyApp` but want to cache its dependencies.
### Using a Specific Configuration
Cache using a specific build configuration:
```bash theme={null}
tuist cache warm --configuration Release
```
By default, Tuist caches using the Debug configuration. Use Release configuration for production CI pipelines.
## Using Cached Binaries
When you generate your project, Tuist automatically uses cached binaries:
```bash theme={null}
tuist generate
```
Targets with available cached binaries are replaced with their pre-built versions. You'll see output like:
```
✓ Using cached binary for MyFramework
✓ Using cached binary for Networking
✓ Building MyApp from source
```
## Cache in CI/CD
Integrate caching into your CI pipeline to speed up builds:
```yaml .github/workflows/build.yml theme={null}
name: Build
on: [push]
jobs:
build:
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
- name: Install Tuist
run: curl -Ls https://install.tuist.io | bash
- name: Authenticate
run: tuist auth login
- name: Warm cache
run: tuist cache warm --configuration Release
- name: Build project
run: tuist build
```
### Branch-Based Caching
Cache is automatically scoped by:
* Project configuration
* Git branch
* Target hashes
This ensures that different branches can have different cached artifacts without conflicts.
## Cache Configuration
Customize cache behavior in your `Config.swift`:
```swift Config.swift theme={null}
import ProjectDescription
let config = Config(
cache: .cache(
path: .relativeToRoot(".tuist/cache"),
profiles: [
.profile(
name: "Simulator",
configuration: "Debug",
device: .iPhone("iPhone 15 Pro")
),
.profile(
name: "Device",
configuration: "Release",
device: .device
)
]
)
)
```
### Cache Profiles
Cache profiles allow you to maintain separate caches for different build configurations:
```bash theme={null}
# Cache for simulator builds
tuist cache warm --profile Simulator
# Cache for device builds
tuist cache warm --profile Device
```
## Checking Cache Configuration
View your current cache configuration:
```bash theme={null}
tuist cache config
```
This displays:
* Cache storage location
* Configured profiles
* Server connection status
## Cache Operations
### Check if a Target is Cached
You can check if specific targets have cached versions available without building:
```bash theme={null}
tuist cache config
```
### Print Cache Hashes
View the cache hashes for all cacheable targets:
```bash theme={null}
tuist hash cache
```
This is useful for:
* Debugging cache misses
* Understanding what triggers cache invalidation
* Verifying cache configuration
## Understanding Cache Hits and Misses
### What Invalidates the Cache?
The cache for a target is invalidated when:
* **Source files** change
* **Build settings** are modified
* **Dependencies** are updated
* **Xcode version** changes (by default)
* **SDK version** changes
### Maximizing Cache Hits
To get the most out of caching:
1. **Modularize your project**: Smaller targets cache independently
2. **Stable dependencies**: Keep third-party dependencies on fixed versions
3. **Consistent build settings**: Avoid configuration-specific customizations
4. **Team alignment**: Ensure everyone uses the same Xcode version
## Cache Storage
Cached artifacts are stored in:
* **Remote**: Tuist Cloud (S3-compatible storage)
* **Local**: `~/.tuist/Cache` on your machine
Local cache is used as a fallback when offline or for faster access.
### Storage Locations
```bash theme={null}
# Local cache directory
~/.tuist/Cache/
# Project-specific cache metadata
.tuist/Cache/
```
## Cache Analytics
Cache usage metrics are automatically sent to Tuist Cloud (if enabled), providing insights into:
* Cache hit/miss rates
* Build time savings
* Storage usage
* Most frequently cached targets
Analyze cache performance in the Insights dashboard
## Advanced Usage
### Content-Addressable Storage (CAS)
Tuist uses content-addressable storage for caching, which:
* Deduplicates identical files across targets
* Enables partial cache downloads
* Optimizes storage efficiency
### Selective Testing with Cache
Use cache data to run only tests affected by your changes:
```bash theme={null}
tuist test --selective
```
Discover how to speed up test runs
## Troubleshooting
### Cache Always Misses
If you're experiencing constant cache misses:
1. Check that everyone uses the same Xcode version
2. Verify build settings are consistent
3. Ensure `.tuist-version` is committed
4. Run `tuist hash cache` to inspect target hashes
### Build Fails with Cached Binaries
If a build fails when using cached binaries:
```bash theme={null}
# Force rebuild without cache
tuist clean
tuist cache warm
tuist generate
```
### Slow Cache Downloads
If cache downloads are slow:
* Check your network connection
* Verify server location is geographically close
* Consider self-hosting for better performance
## Best Practices
Set up CI to warm the cache after every merge to main. This ensures developers always have recent cached artifacts.
Create separate profiles for simulator vs device builds, debug vs release, etc.
Track cache hit rates in the Insights dashboard to identify optimization opportunities.
Lock third-party dependency versions to maximize cache reuse across the team.
## Next Steps
Use cache data to run only affected tests
Analyze cache performance and build metrics