Skip to main content
Tuist’s binary caching feature dramatically reduces build times by caching framework and library binaries, allowing you to reuse previously built artifacts instead of recompiling everything from scratch.

​
Overview

Binary caching works by:
  • Computing content hashes for your targets based on source files, dependencies, and build configuration
  • Storing compiled binaries in local or remote storage
  • Replacing targets with their cached binaries when the content hasn’t changed
  • Warming the cache in CI to speed up local development
Tuist intelligently determines which targets are cacheable. Only frameworks, static frameworks, bundles, and macros are eligible for caching.

​
How It Works

​
Content Hashing

Tuist generates a unique hash for each target based on:
  1. Source files - All Swift, Objective-C, and resource files
  2. Dependencies - Both direct and transitive dependencies
  3. Build settings - Configuration, Swift version, and compiler flags
  4. Cache version - Tuist’s cache version to invalidate incompatible artifacts
// Automatically excluded from cache:
// - Targets that depend on XCTest
// - Excluded targets you specify
// - Non-cacheable product types (apps, tests)

​
Cache Storage

Tuist supports two storage options:

Local Cache

Fast, disk-based cache stored on your machine. Perfect for individual developers.

Remote Cache

Shared cache stored in Tuist Cloud. Enables team-wide cache sharing and CI/CD acceleration.

​
Getting Started

​
Enable Binary Cache

By default, binary caching is enabled for all Tuist projects. To use it:
1

Generate with cache

Run your project with caching enabled:
tuist generate
The first generation will build everything and populate the cache.
2

Build your project

Build your project in Xcode. Tuist will cache the compiled frameworks.
3

Clean and regenerate

tuist clean
tuist generate
Watch as Tuist restores cached binaries instead of recompiling!

​
Warm the Cache in CI

Speed up CI builds by pre-building and caching frameworks: 
# In your CI script
tuist cache warm
This builds all cacheable targets and stores them for future runs.

​
Remote Caching

Share cache artifacts across your team using Tuist Cloud.

​
Setup

1

Authenticate

tuist auth
2

Link your project

tuist project create
3

Use remote cache

Tuist automatically uses remote cache when authenticated. No additional configuration needed!
Remote cache is transparent. Tuist checks the remote cache first, falls back to local cache, and finally rebuilds if necessary.

​
Configuration

​
Exclude Targets from Cache

Some targets shouldn’t be cached (e.g., frequently changing code): 
tuist generate --no-cache
Or exclude specific targets when warming the cache: 
tuist cache warm --exclude TargetName

​
Disable Binary Cache

If you need to build everything from source: 
tuist build --no-binary-cache
tuist test --no-binary-cache

​
Cache Invalidation

The cache is automatically invalidated when:
  • Source files change - Any modification to Swift, Objective-C, or resource files
  • Dependencies change - Updates to SPM packages, CocoaPods, or local dependencies
  • Build settings change - Configuration, compiler flags, or Swift version updates
  • Cache version bumps - Tuist updates that change the cache format
Clean builds ignore the cache. Use tuist clean to force rebuilding all targets.

​
Best Practices

  • Break your app into multiple frameworks
  • Separate stable code from frequently changing code
  • Use explicit dependencies instead of implicit ones
  • Keep framework interfaces stable
  • Run tuist cache warm as the first step in CI
  • Cache the ~/.tuist/Cache directory between CI runs
  • Use remote cache to share artifacts across CI jobs
Check if a target is being cached:
tuist cache
Clear local cache:
rm -rf ~/.tuist/Cache

​
Performance Impact

First Build

Standard build timeNo cache available

Cached Build

70-90% fasterOnly changed targets rebuild

Full Cache

95%+ fasterNo compilation needed

​
Troubleshooting

  • Verify tuist generate completed successfully
  • Check if targets are cacheable (frameworks, not apps)
  • Ensure you’re not using --no-cache flag
  • Verify remote authentication with tuist auth
  • Run tuist clean to clear local cache
  • Verify source files are properly tracked in git
  • Check for uncommitted changes that affect hashing
  • Verify network connectivity
  • Check authentication status
  • Ensure project is properly linked to Tuist Cloud

​
Next Steps

Selective Testing

Only run tests affected by your changes

Build Insights

Analyze build performance and cache efficiency