Quick start

The fastest path is kache init. It edits ~/.cargo/config.toml to set rustc-wrapper = "kache", installs the background daemon as a login service, and starts it. The whole flow takes a few seconds and is idempotent — re-run it any time to repair configuration.

# interactive setup
kache init

# or accept all defaults non-interactively
kache init -y

# skip the login service if you'd rather start the daemon manually
kache init --no-service

# check what init would do without changing anything
kache init --check

After kache init, your next cargo build is already cached. The first run is a normal cold compile; the second run restores everything from kache's store via hardlinks.

kache: cold build populates the store, then cargo clean && cargo build restores every artifact via hardlinks

Verify the setup

kache doctor

doctor checks for a working RUSTC_WRAPPER, conflicting wrappers (e.g. sccache), config file problems, and daemon connectivity. Add --fix to apply automatic repairs, or --verify to additionally walk the store and confirm cached blobs are intact.

Manual setup (without `kache init`)

If you'd rather wire things up yourself:

Set the wrapper for your current shell session

export RUSTC_WRAPPER=kache

Or persist it in ~/.cargo/config.toml so it applies to every project:

[build]
rustc-wrapper = "kache"

The ~/.cargo/config.toml approach is more convenient for daily use. The env var is handy for CI or when you want to test kache on a single project without changing global config.

Run a build

cargo build

The first build runs normally — kache compiles each crate and stores the result. You'll see normal cargo output.

Run the build again

cargo clean && cargo build

This time, kache restores every crate from the cache via hardlinks. Cargo should complete in seconds for a project with no source changes.

Open the monitor

kache

The TUI monitor opens and shows the Build tab with the events from the last run — each crate listed as a local hit or miss with timing. Press q to quit.

How to tell it's working

In CI or any non-terminal environment, kache prints a progress line to stderr for each crate:

[kache] serde: local hit (2ms, 1.2 MB)
[kache] tokio: local hit (3ms, 4.8 MB)
[kache] myapp: miss (1.4s, 892 KB)

In a terminal, these lines are suppressed — open the monitor instead (kache or kache monitor).

You can also check the cache state directly:

kache list               # all cached crates, sorted by name
kache list serde         # details for a specific crate
kache stats              # one-shot summary (no UI)

What kache does not cache

By default, kache skips binary crates (bin), dynamic libraries (dylib, cdylib), and proc-macros. These outputs depend on the linker and are more expensive to restore correctly. Set KACHE_CACHE_EXECUTABLES=1 or cache_executables = true in the config file to opt in.

Incremental compilation is automatically disabled when kache is active (CARGO_INCREMENTAL=0). kache's artifact caching makes incremental redundant, and on macOS, APFS-related corruption can occur when both are active simultaneously.

Disabling kache temporarily

KACHE_DISABLED=1 cargo build

Even when disabled, kache strips incremental flags to avoid the APFS issue on macOS.