Skip to content
Skip to Content
Getting Started

Upgrading to v2

Install the paired binaries, keep your configuration, and verify reuse

Keep using cargo, Make, CMake, or Ninja after upgrading. V2 changes how Kache executes and coordinates compiler work; it does not add a kache build command.

Choose the version

V2.0.0 was the first stable v2 release. Install the current stable version with Cargo:

cargo install kache --locked --version 2.1.1

Unversioned commands select the latest stable release. See Installation for prebuilt packages. The steps below apply to upgrades from 1.x, v2 previews, and earlier stable v2 releases.

Upgrade the complete installation

  1. Finish active builds.
  2. Upgrade with the same package manager, or install both kache and kache-engine from the same release archive into the same directory.
  3. Keep your existing Cargo wrapper and Kache configuration.
  4. Restart the daemon and verify the installation:
kache --version
kache daemon restart
kache doctor
kache doctor --probe

--probe compiles a temporary Rust library twice and checks that the second compile is a local hit. It uses an isolated cache and no remote. A successful probe verifies the local path, not your remote's write permissions.

V2 release archives contain the companion engine, including the Windows ZIP. Update Docker COPY instructions and custom installers that previously copied only kache. Package managers and cargo install install the pair.

Existing services and compiler shims that launch kache remain usable when the pair is installed at the same paths. Run kache init --check to inspect setup changes. Run kache init to refresh shell completions after upgrading; a new terminal loads the updated scripts.

Existing build-script launchers can keep using the engine copy pinned when the script was built. Restarting the daemon does not rebuild Cargo Fresh units. If an affected script still shows old behavior, rebuild that package's outputs; see Build scripts. A blanket cache delete is not required.

Older prediction metadata

RC.2 can bypass build-script caching when an inherited index still has the older prediction-table layout. RC.3 and later discard those incompatible predictions and learn them again from source. Compiled entries stay in the store; no manual cache deletion is needed.

Historical errors remain in explain --all. V2.0.0 groups recognized failures from older versions under "Earlier Kache bugs". The report also shows the versions that recorded a build and the version currently installed.

Expect some cold state

Your local store does not need a blanket delete. Kache can migrate its index, while changed cache-key recipes cause compatible work to be rebuilt under new keys. Managed incremental state from older layouts starts cold and is recreated with private files. Imported seeds never share writable inodes with a donor.

Cargo can still report a package as Fresh without invoking Kache. Use the two-worktree quick start to test actual restores, then inspect:

kache stats --last-build
kache explain

Older builds may show Details missing. Enable [cache] explain_miss = true before rebuilding to record future key differences. An upgrade cannot recover fields absent from the retained history.

Find the v2 workflow

  • Worktrees and incremental builds: artifact reuse, new-target seeding, private incremental state, and cleanup previews.
  • Configuration: file selection, host settings, and scriptable edits.
  • Monitor: select a build, inspect its events, and open Why.
  • Blaze: opt into a separate local compiler/cache.
  • Architecture: client, engine, daemon, and fallback boundaries.
Available for:
Apple macOS logomacOSMicrosoft Windows logoWindowsLinux logoLinux
Download Kunobi