CCACHE(1)

✨ NAME ✨

okay bestie, welcome to the ccache(1) page — yes, manual name ccache, section 1, we’re in the right place 💅

ccache — a fast C/C++ compiler cache. literally iconic behavior.

---

🌸 SYNOPSIS 🌸

ccache [ccache options]
ccache [KEY=VALUE ...] compiler [compiler options]
compiler [compiler options]

so there are three forms, and they are giving very different energy:

• the first form takes the options listed in COMMAND LINE OPTIONS below 👇
• the second form runs the compiler, and you can optionally pass configuration options as KEY=VALUE arguments
• the third form is when ccache is masquerading as the compiler, as described in RUN MODES

---

🎀 DESCRIPTION 🎀

ccache is a compiler cache that speeds up recompilation by storing the results of previous compilations and reusing them when the same compilation is performed again. no cap, it just remembers stuff so you don’t have to wait around again 😭✨

ccache is designed to produce exactly the same compiler output as a normal compilation. the only difference you should notice is faster build times. any known exceptions to this behavior are documented in the CAVEATS section. if you find a case where ccache produces different output than expected, please report it to us 🫶

---

🦋 RUN MODES 🦋

there are exactly two ways to use ccache to cache compilations:

1. Prefix method: add ccache before your compilation command. this is the simplest approach when you want to try ccache or use it for specific projects. example:

ccache gcc -c example.c

2. Masquerade method: make ccache appear as the compiler by creating a symbolic link to ccache with the compiler’s name. this is useful when you want to use ccache for all compilations. to set up ccache to masquerade as gcc and g++:

cp ccache /usr/local/bin/
ln -s ccache /usr/local/bin/gcc
ln -s ccache /usr/local/bin/g++

on systems that don’t support symbolic links, you can copy ccache instead:

cp ccache /usr/local/bin/gcc
cp ccache /usr/local/bin/g++

this works as long as the directory containing the symbolic links or ccache copies appears before the real compiler directory (typically /usr/bin) in your PATH.

⚠️ Warning the masquerade method works well but may conflict with other tools that use the same technique. see USING CCACHE WITH OTHER COMPILER WRAPPERS for more information.

💅 COMMAND LINE OPTIONS 💅

Okay so bestie, listen — these command line options are only for when you're calling ccache directly, like actually typing "ccache" yourself. When ccache is out here masquerading as a compiler (you know, the whole thing from the last section), you just use your normal compiler options and go read your compiler's docs, k? ✨

---

🎀 Common options 🎀

• -c, --cleanup — Cleans up the cache by yeeting out not-recently-used cached files until you're under the specified file number and cache size limits. It also recalculates the cache file count and size totals, slay. Ngl you normally don't need to run this manually — ccache keeps the cache below the limits at runtime and keeps the stats updated on every compilation. Forcing a cleanup is mostly useful if you've messed with the cache contents yourself or you think the cache size stats are lying to you. 🙈
• -C, --clear — Nukes the entire cache, removing all cached files, but keeps the configuration file. Like, all of it. Gone. ✨
• --config-path PATH — Lets the command line options operate on configuration file PATH instead of the default one. Using this is literally the same effect as temporarily setting (overriding) the environment variable CCACHE_CONFIGPATH. 💖
• -d, --dir PATH — Lets the command line options operate on cache directory PATH instead of the default. Like, say you wanna show stats for a cache directory at /shared/ccache, you'd run ccache -d /shared/ccache -s. Same effect as temporarily setting the environment variable CCACHE_DIR. 🫶
• --dry-run — Does not perform any write operations. Just vibes, no changes. ✨
• --evict-namespace NAMESPACE — Removes files created in the given namespace from the cache. Bye bestie 👋
• --evict-older-than AGE — Removes files used less recently than AGE from the cache. AGE should be an unsigned integer with a d (days) or s (seconds) suffix. If you combine it with --evict-namespace, it only removes files within that namespace. 🧚
• -h, --help — Prints a summary of command line options. The classic. 💅
• -F NUM, --max-files NUM — Sets the maximum number of files allowed in the cache to NUM. Use 0 for no limit. The value gets stored in a configuration file in the cache directory and applies to all future compilations. 👑
• -M SIZE, --max-size SIZE — Sets the maximum size of the files stored in the cache. SIZE should be a number followed by an optional suffix: kB, MB, GB, TB (decimal), KiB, MiB, GiB or TiB (binary). Default suffix is GiB. Use 0 for no limit. The value is stored in a configuration file in the cache directory and applies to all future compilations. 💖
• -X LEVEL, --recompress LEVEL — Recompresses the cache to level LEVEL using the Zstandard algorithm. The level can be an integer, with the same semantics as the compression_level configuration option, or the special value uncompressed for no compression. See CACHE COMPRESSION for more info (iykyk). Heads up: this can potentially take a long time since all files in the cache need to be visited 😭. Only files currently compressed with a different level than LEVEL get recompressed, so that's something.
• -o KEY=VALUE, --set-config KEY=VALUE — Sets configuration option KEY to VALUE in the configuration file. See CONFIGURATION for more. ⭐
• -x, --show-compression — Prints cache compression statistics. See CACHE COMPRESSION for more. Also potentially takes a long time since all files in the cache need to be visited 💀.
• -p, --show-config — Prints current configuration options and where they originate from (environment variable, configuration file or compile-time default) in human-readable format. Detective mode 🔍
• --show-log-stats — Prints statistics counters from the stats log in human-readable format. See stats_log. Use -v/--verbose once or twice for more details. 🌸
• -s, --show-stats — Prints a summary of configuration and statistics counters in human-readable format. Use -v/--verbose once or twice for more details. See Cache statistics for more info. 📊
• --stop-storage-helpers — Storage helpers normally stop after a period of client inactivity, but this option stops any running helpers immediately. Like ripping off the band-aid 🩹
• --threads THREADS — Uses up to THREADS threads for threaded operations. Default is one thread per CPU. Multi-core girlie behavior 💅
• -v, --verbose — Increases verbosity. You can give this option multiple times. Say it with your chest 📢
• -V, --version — Prints version and copyright information. 👑
• -z, --zero-stats — Zeros the cache statistics (but not the configuration options). Fresh start energy ✨

---

🦋 Options for remote file-based storage 🦋

• --trim-dir PATH — Removes not-recently-used files from directory PATH until it's at most the size specified by --trim-max-size.

⚠️ Warning ⚠️ Do not use this option to trim the local cache, bestie, I'm serious 😭. To trim the local cache directory to a certain size, use CCACHE_MAXSIZE=SIZE ccache -c.

• --trim-max-size SIZE — Specifies the maximum size for --trim-dir. SIZE should be a number followed by an optional suffix: kB, MB, GB, TB (decimal), KiB, MiB, GiB or TiB (binary). The default suffix is GiB. Use 0 for no limit. 🔥
• --trim-method METHOD — Specifies the method to trim a directory with --trim-dir. Possible values are:
  • atime — LRU (least recently used) using the file access timestamp. This is the default. ⏰
  • mtime — LRU (least recently used) using the file modification timestamp. 📝
• --trim-recompress LEVEL — Recompresses to level LEVEL using the Zstandard algorithm when using --trim-dir. The level can be an integer, with the same semantics as the compression_level configuration option, or the special value uncompressed for no compression. See CACHE COMPRESSION for more. This can potentially take a long time since all files in the cache need to be visited 😭. Only files currently compressed with a different level than LEVEL get recompressed, ok?

---

🧚 Options for scripting or debugging 🧚

• --checksum-file PATH — Prints the checksum (128 bit XXH3) of the file at PATH (- for standard input). 🔍
• --extract-result PATH — Extracts data stored in the result file at PATH (- for standard input). The data gets written to ccache-result.* files in the current working directory. This option is only useful when debugging ccache and its behavior. 🐛
• --format FORMAT — Specifies format for --print-log-stats and --print-stats. Possible values are:
  • tab — Tab separated. This is the default. 📑
  • json — JSON formatted. 🧾
• -k KEY, --get-config KEY — Prints the value of configuration option KEY. See CONFIGURATION for more. 💖
• --hash-file PATH — Prints the hash (160 bit BLAKE3) of the file at PATH (- for standard input). This is only useful when debugging ccache and its behavior. 🔐
• --inspect PATH — Prints the content of a result or manifest file at PATH (- for standard input) to standard output in human-readable format. File content embedded in a result file will however not be printed — use --extract-result to extract the file content. This option is only useful when debugging ccache and its behavior. 👀
• --print-log-stats — Prints statistics counters from the stats log in machine-parsable (tab-separated or JSON) format. See stats_log and --format. 🤖
• --print-stats — Prints statistics counter IDs and corresponding values in machine-parsable (tab-separated or JSON) format. See --format. 🤖
• --print-version — Prints version and does nothing else. Periodt. ✨

---

🌈 Extra options 🌈

When run as a compiler, ccache usually just takes the same command line options as the compiler you're using. The only exception to this is the option --ccache-skip. That option tells ccache to avoid interpreting the next option in any way and to pass it along to the compiler as-is. 💅

📌 Note --ccache-skip currently only tells ccache not to interpret the next option as a special compiler option — the option will still be included in the direct mode hash.

The reason this matters, bestie, is that ccache genuinely needs to parse the command line and figure out what's an input filename and what's a compiler option, because it needs the input filename to determine the name of the resulting object file (among other things). The heuristic ccache uses when parsing the command line is that any argument that exists as a file gets treated as an input file name. By using --ccache-skip you can force an option to not be treated as an input file name and instead be passed along to the compiler as a command line option. 🫶

Another case where --ccache-skip comes in clutch is if ccache interprets an option specially but shouldn't, since the option has another meaning for your compiler than what ccache thinks. 😭

See also ignore_options. 👑

---

💜 CONFIGURATION 💜

You can customize ccache's behavior using configuration files and environment variables. Configuration options are processed in this order of priority (highest first), no cap:

1. Command line settings in KEY=VALUE form. Example:

ccache debug=true compiler_check="%compiler% --version" gcc -c example.c

1. Environment variables starting with CCACHE_.
1. A directory-specific configuration file.
1. The cache-specific configuration file.
1. The system-wide configuration file <sysconfdir>/ccache.conf (typically /etc/ccache.conf or /usr/local/etc/ccache.conf).
1. Compile-time defaults.

Exception: If the environment variable CCACHE_CONFIGPATH is set, it specifies the only configuration file that will be read (environment variables and command line settings still apply). 🚨

---

🌸 Cache-specific configuration file 🌸

The location of the cache-specific configuration file is determined like this on non-Windows systems:

1. If CCACHE_CONFIGPATH is set, use that path.
1. Otherwise, if the environment variable CCACHE_DIR is set then use $CCACHE_DIR/ccache.conf.
1. Otherwise, if cache_dir is set in the system configuration file then use <cache_dir>/ccache.conf.
1. Otherwise, if there's a legacy $HOME/.ccache directory then use $HOME/.ccache/ccache.conf.
1. Otherwise, if XDG_CONFIG_HOME is set then use $XDG_CONFIG_HOME/ccache/ccache.conf.
1. Otherwise, use $HOME/Library/Preferences/ccache/ccache.conf (macOS) or $HOME/.config/ccache/ccache.conf (other systems).

On Windows, this is the method used to find the configuration file:

1. If CCACHE_CONFIGPATH is set, use that path.
1. Otherwise, if the environment variable CCACHE_DIR is set then use %CCACHE_DIR%/ccache.conf.
3. Otherwise, if cache_dir is set in the system configuration file then use <cache_dir>\ccache.conf. The system-wide configuration on Windows is %ALLUSERSPROFILE%\ccache\ccache.conf by default. The ALLUSERSPROFILE environment variable is usually C:\ProgramData. 🪟
4. Otherwise, if there is a legacy %USERPROFILE%\.ccache directory then use %USERPROFILE%\.ccache\ccache.conf.
5. Otherwise, use %LOCALAPPDATA%\ccache\ccache.conf if it exists.
6. Otherwise, use %APPDATA%\ccache\ccache.conf.

See also the cache_dir configuration option for how the cache directory location is determined. 🔍

🎀 Directory-specific configuration file 🎀

ccache searches for a ccache.conf file (separate from the cache-specific configuration file described above) in the current working directory or any parent directory. The found file must be owned by the effective user and must not be world-writable; otherwise ccache will abort with an error. The search stops when reaching:

• a directory listed in a "ceiling directory" (by default the user’s home directory)
• a directory that contains a "ceiling marker" (by default .git)
• a directory owned by another user
• a file system boundary (mount point)

By default, the file cannot set "unsafe options", i.e. those that affect which commands to execute, which files to write (except cache entries) and which remote storage to use. It is possible to allow unsafe options by adding an entry to safe_dirs. 🛑

🧚 Configuration value syntax 🧚

All configuration values support expansion of environment variables. The syntax is similar to POSIX shell syntax: $VAR or ${VAR}. Both variants will expand to the value of the environment variable VAR.

Two consecutive dollar signs ($$) will expand to a single dollar sign ($). 💸

✨ Configuration file syntax ✨

Configuration files are in a simple “key = value” format, one option per line. Lines starting with a hash sign are comments. Blank lines are ignored, as is whitespace surrounding keys and values. Example:

# Set maximum cache size to 10 GB:
max_size = 10GB

🌸 Multi-line values 🌸

Values can span multiple lines using indentation-based continuation. Lines that start with whitespace (spaces or tabs) are treated as continuation lines and are joined to the previous value with a single space. Comments and blank lines within a multi-line value are skipped. For example:

ignore_options =
  -Wall
  -Wextra
  # This is a comment within the value
  -pedantic
# This ends the multi-line value
compiler = gcc

This is equivalent to:

ignore_options = -Wall -Wextra -pedantic
compiler = gcc

Multi-line values are particularly useful for options that accept multiple items. 🧺

🍓 Boolean values 🍓

Some configuration options are boolean values (i.e. truth values). In a configuration file, such values must be set to the string true or false. For the corresponding environment variables, the semantics are a bit different:

• A set environment variable means “true” (even if set to the empty string).
• The following case-insensitive negative values are considered an error (instead of surprising the user): 0, false, disable and no.
• An unset environment variable means “false”.

Each boolean environment variable also has a negated form starting with CCACHE_NO. For example, CCACHE_COMPRESS can be set to force compression and CCACHE_NOCOMPRESS can be set to force no compression. ✅❌

🧵 Path lists 🧵

Options that define a list of paths have their entries separated by ; on Windows and : on other systems.

👑 Configuration options 👑

Below is a list of available configuration options. The corresponding environment variable name is indicated in parentheses after each configuration option key.

absolute_paths_in_stderr (CCACHE_ABSSTDERR)

This option specifies whether ccache should rewrite relative paths in the compiler’s textual output (standard error and standard output) to absolute paths. This can be useful if you use base_dir with a build system (e.g. CMake with the "Unix Makefiles" generator) that executes the compiler in a different working directory, which makes relative paths in compiler errors or warnings incorrect. The default is false. 🛠️

base_dir (CCACHE_BASEDIR)

This option specifies a list of absolute paths. When set, ccache converts absolute paths to relative paths before sending them to the compiler (or including them in the input hash), but only for paths that start with one of the specified base directories. "Relative" here means "relative to the current working directory". 📁

This enables cache sharing between compilations in different directories, even when the project uses absolute paths. See COMPILING IN DIFFERENT DIRECTORIES_ for more details. When empty (the default), no path rewriting occurs.

Avoid using / as the base directory as this will also rewrite system header paths, which is usually counterproductive. 🚫

Example scenario: Alice works in /home/alice/project1/build and compiles like this:

ccache gcc -I/usr/include/example -I/home/alice/project2/include -c /home/alice/project1/src/example.c

Here is what ccache will actually execute for different base_dir settings:

# Current working directory: /home/alice/project1/build

# With "base_dir = /":
gcc -I../../../../usr/include/example -I../../project2/include -c ../src/example.c

# With "base_dir = /home" or "base_dir = /home/alice":
gcc -I/usr/include/example -I../../project2/include -c ../src/example.c

# With "base_dir = /home/alice/project1" or "base_dir = /home/alice/project1/src":
gcc -I/usr/include/example -I/home/alice/project2/include -c ../src/example.c

If Bob stores the same projects in /home/bob/stuff and both users set base_dir to /home or /home/$USER, they will share cache hits because the rewritten command lines will be identical:

# Current working directory: /home/bob/stuff/project1/build

# With "base_dir = /home" or "base_dir = /home/bob":
gcc -I/usr/include/example -I../../project2/include -c ../src/example.c

Without base_dir there will be a cache miss since the absolute paths will differ. With base_dir set to / there will be a cache miss since the relative path to /usr/include/example will be different. With base_dir set to /home/bob/stuff/project1 there will a cache miss since the path to project2 will be a different absolute path. 😭

Warning Rewriting absolute paths to relative is kind of a brittle hack. It works OK in many cases, but there might be cases where things break. One known issue is that absolute paths are not reproduced in dependency files, which can mess up dependency detection in tools like Make and Ninja. If possible, use relative paths in the first place instead of using base_dir. 💀

cache_dir (CCACHE_DIR)

This option specifies where ccache will keep its cached compiler outputs. 🎁

On non-Windows systems, the default is $HOME/.ccache if such a directory exists, otherwise $XDG_CACHE_HOME/ccache if XDG_CACHE_HOME is set, otherwise $HOME/Library/Caches/ccache (macOS) or $HOME/.cache/ccache (other systems).

On Windows, the default is %USERPROFILE%\.ccache if such a directory exists, otherwise %LOCALAPPDATA%\ccache.

Warning Previous ccache versions defaulted to storing the cache in %APPDATA%\ccache on Windows. This can result in large network file transfers of the cache in domain environments and similar problems. Please check this directory for cache directories and either delete them or the whole directory, or move them to the %LOCALAPPDATA%\ccache directory. 🌐

See also Cache-specific configuration file.

ceiling_dirs (CCACHE_CEILING_DIRS)

This option specifies absolute directories where ccache will stop searching for a directory-specific configuration file. You might want to set this if accessing files in parent directories is too slow, e.g. on network file systems. The default is to stop looking when reaching the user’s home directory. 🏠

ceiling_markers (CCACHE_CEILING_MARKERS)

This option specifies one or more file or directory names (separated by ; on Windows, : on other systems). When searching for a directory-specific configuration file, ccache will stop searching parent directories when it reaches a directory containing any of the specified names. The default is .git. 🧭

compiler (CCACHE_COMPILER or (deprecated) CCACHE_CC)

This option can be used to force the name of the compiler to use. If set to the empty string (which is the default), ccache works it out from the command line. 🧑‍💻

compiler_check (CCACHE_COMPILERCHECK)

By default, ccache includes the modification time (“mtime”) and size of the compiler in the hash to ensure that results retrieved from the cache are accurate. If compiler plugins are used, these plugins will also be added to the hash. This option can be used to select another strategy. Possible values are:

• content — Hash the content of the compiler binary. This makes ccache very slightly slower compared to mtime, but makes it cope better with compiler upgrades during a build bootstrapping process.
• mtime — Hash the compiler’s mtime and size, which is fast. This is the default.
• none — Don’t hash anything. This may be good for situations where you can safely use the cached results even though the compiler’s mtime or size has changed (e.g. if the compiler is built as part of your build system and the compiler’s source has not changed, or if the compiler only has changes that don’t affect code generation). You should only use none if you know what you are doing.
• string:value — Hash value. This can for instance be a compiler revision number or another string that the build system generates to identify the compiler.
• a command string — Hash the standard output and standard error output of the specified command. The string will be split on whitespace to find out the command and arguments to run. No other interpretation of the command string will be done, except that the special word %compiler% will be replaced with the path to the compiler. Several commands can be specified with ; as the separator. Examples:

%compiler% -v

%compiler% -dumpmachine; %compiler% -dumpversion

Okay so real talk about this one: make sure the command you give is as fast as it possibly can be, because ccache runs it once for every single ccache invocation. Every. Single. One. 💀

So why would you even want to identify the compiler with a command? Two big mood reasons:

• It's useful when you want to dodge cache misses after the compiler got rebuilt but didn't actually change. Same compiler, fresh mtime, no drama. ✨
• The other case is when the compiler ccache sees isn't the real compiler at all but another compiler wrapper on top. In that situation the default mtime method hashes the mtime and size of that other wrapper, which means ccache literally can't tell when the compiler got upgraded. Using a suitable command to identify the compiler is safer, sure, but it's also slower — so lowkey consider sticking with the mtime method combined with the prefix_command option if you can. Go read USING CCACHE WITH OTHER COMPILER WRAPPERS for the whole story. 🫶

compiler_type (CCACHE_COMPILERTYPE)

ccache normally just vibes its way into guessing the compiler type from the compiler's name. The compiler_type option lets you force the type instead. Iconic when your compiler has a non-standard name but is secretly one of the known types. Possible values:

• auto — guess one of the types below based on the compiler name (following symlinks). This is the default. 🎀
• clang — Clang-based compiler.
• clang-cl — clang-cl.
• gcc — GCC-based compiler.
• icl — Intel compiler on Windows.
• icx — Intel LLVM-based compiler.
• icx-cl — Intel LLVM-based MSVC-compatible compiler.
• msvc — Microsoft Visual C++ (MSVC).
• nvcc — NVCC (CUDA) compiler.
• qcc — QCC (QNX) compiler.
• other — any compiler other than the known types. 🙈

compression (CCACHE_COMPRESS or CCACHE_NOCOMPRESS, see Boolean values above)

If true, ccache compresses the data it puts in the cache. ✨ But heads up: this option does not affect how files are retrieved — compressed and uncompressed results both stay perfectly usable no matter what you set here. Default is true.

The compression is done with the Zstandard algorithm, and it's fast enough that there's basically little reason to turn it off for performance. One exception: if your cache lives on a compressed file system, then ccache's compression is just redundant at that point. 😭

Also, compression gets disabled if file cloning (the file_clone option) or hard linking (the hard_link option) is enabled. That's just how it is.

compression_level (CCACHE_COMPRESSLEVEL)

This one sets the level at which ccache compresses object files, using the real-time compression algorithm Zstandard. It only does anything if compression is enabled — which it is, by default. 💅 Zstandard is extremely fast at decompressing and very fast at compressing on lower levels. Default is 0.

Semantics of compression_level, bestie:

• > 0 — a positive value maps to normal Zstandard compression levels. Lower levels (e.g. 1) mean faster compression but a worse compression ratio. Higher levels (e.g. 19) mean slower compression but a better ratio. The max possible value depends on the libzstd version, but at least up to 19 is available on all versions. Decompression speed is essentially the same across all levels. Rule of thumb: use level 5 or lower, because higher levels can slow down compilations noticeably. Higher levels are still useful when recompressing the cache with the command line option -X/--recompress. 🔥
• < 0 — a negative value maps to Zstandard's "ultra-fast" compression levels, which are even faster than level 1 but with less good ratios. For instance, level -3 corresponds to --fast=3 for the zstd command line tool. In practice there's little use for anything lower than -5 or so.
• 0 (default) — the value 0 means ccache picks a suitable level for you, currently 1. 🎀

See the Zstandard documentation at https://facebook.github.io/zstd/ for more info.

debug (CCACHE_DEBUG or CCACHE_NODEBUG, see Boolean values above)

If true, debug mode is on. 🔍 Debug mode creates per-object debug files that are genuinely so helpful when you're debugging unexpected cache misses. But ngl, ccache performance drops slightly. See CACHE DEBUGGING. Default is false.

debug_dir (CCACHE_DEBUGDIR)

Tells ccache where to write those per-object debug files when debug mode is on. If set to the empty string, files get written right next to the object file. If set to a directory, the debug files are written with full absolute paths inside that directory, and ccache creates it if it's not there yet. Default is the empty string.

Example time, because this one's confusing: if debug_dir is set to /example, your current working directory is /home/user, and the object file is build/output.o, then the debug log lands at /example/home/user/build/output.o.ccache-log. 🦋 See also CACHE DEBUGGING.

debug_level (CCACHE_DEBUGLEVEL)

Sets how much info gets written when debug mode is enabled. See CACHE DEBUGGING. Default is 2.

depend_mode (CCACHE_DEPEND or CCACHE_NODEPEND, see Boolean values above)

If true, the depend mode is used. Default is false. See The depend mode.

direct_mode (CCACHE_DIRECT or CCACHE_NODIRECT, see Boolean values above)

If true, the direct mode is used. Default is true. See The direct mode. 💖

disable (CCACHE_DISABLE or CCACHE_NODISABLE, see Boolean values above)

When true, ccache just calls the real compiler and bypasses the cache completely. Default is false.

Bonus feature: you can also disable ccache for one specific source file by dropping the string ccache:disable in a comment within the first 4096 bytes of the file. Cute, right? 🎀

extra_files_to_hash (CCACHE_EXTRAFILES)

A list of paths to files that ccache will include in the hash sum that identifies the build. Slap anything in here that should bust the cache.

file_clone (CCACHE_FILECLONE or CCACHE_NOFILECLONE, see Boolean values above)

If true, ccache attempts to use file cloning (also known as "copy on write", "CoW" or "reflinks") to store and fetch cached compiler results. file_clone takes priority over hard_link. Default is false. 🦋

Files stored by cloning can't be compressed, so your cache size will likely get significantly larger if you enable this. That said, performance may improve depending on your use case.

Unlike the hard_link option, file_clone is completely safe to use — it's just that not every file system supports the feature. On those, ccache falls back to plain copying (or hard links if hard_link is enabled). No cap. ✨

hard_link (CCACHE_HARDLINK or CCACHE_NOHARDLINK, see Boolean values above)

If true, ccache attempts to use hard links to store and fetch cached object files. Default is false.

Files stored via hard links can't be compressed either, so the cache size will likely be significantly larger with this on. Performance may improve depending on use case, but—

⚠️ Warning — do not enable this option unless you're fully aware of these caveats:

• If the resulting file gets modified, the file in the cache gets modified too, since they share content — which corrupts the cache entry. As of version 4.0, ccache makes stored and fetched object files read-only as a safety measure. On top of that, a simple integrity check runs on cached object files by verifying their sizes are correct. That means mistakes like strip file.o or echo >file.o get detected even if the object file is made writable — but a modification that doesn't change the file size? Not detected. 💀
• Programs that don't expect files from two different identical compilations to be hard links to each other can fail.
• Programs that rely on modification times (like make) can get confused if several users (or one user with several build trees) share the same cache directory. The reason: object files share i-nodes, and therefore modification times. If file.o is in build tree A (hard-linked from the cache) and file.o then gets produced by ccache in build tree B by hard-linking from the cache, the modification timestamp updates for file.o in build tree A too. That can retrigger relinking in build tree A even though literally nothing really changed. 😭

hash_dir (CCACHE_HASHDIR or CCACHE_NOHASHDIR, see Boolean values above)

If true (which is the default), ccache includes the current working directory (CWD) in the hash used to distinguish two compilations when generating debug info (compiler option -g with variations). Exception: the CWD is not included if the compiler options -fdebug-prefix-map or -fdebug-compilation-dir are used appropriately. See also the discussion under COMPILING IN DIFFERENT DIRECTORIES.

Why include the CWD by default? To prevent a problem with storing the current working directory in an object file's debug info — which can lead ccache to hand you back a cached object file whose debug info has the working directory set incorrectly. 🙈

You can disable this option to get cache hits when compiling the same source code in different directories, if you don't mind that the CWD in the debug info might be incorrect.

ignore_headers_in_manifest (CCACHE_IGNOREHEADERS)

A list of paths to files (or directories containing headers) that ccache will not include in the manifest list that makes up the direct mode. Lowkey important: this can cause stale cache hits if those headers do actually change. 👀

• ignore_options (CCACHE_IGNOREOPTIONS) — bestie, this is a space-delimited list of compiler options ccache is just gonna… ignore. Entries can optionally end with an asterisk (*) so they match any option suffix — like, -fmessage-length=* matches both -fmessage-length=20 and -fmessage-length=70. Slay. A matching compiler option will neither be interpreted specially nor be part of the input hash. Why would you ignore something from the hash? Honestly two moods: you know it doesn't affect the result (and ccache doesn't know that), or it does and you simply don't care. See also Extra options.
• inode_cache (CCACHE_INODECACHE or CCACHE_NOINODECACHE, see Boolean values above) — If true, ccache caches source file hashes based on device, inode and timestamps. This lowkey reduces the time spent hashing include files since the result can be reused between compilations. Default is true. Heads up: the feature requires temporary_dir to be on a local filesystem of a supported type.

Note ✨ Support for the inode cache feature on Windows is experimental. On Windows the default is false. 💀

• keep_comments_cpp (CCACHE_COMMENTS or CCACHE_NOCOMMENTS, see Boolean values above) — If true, ccache will NOT discard the comments before hashing preprocessor output. Default is false. This can be used to check documentation with -Wdocumentation. 🎀
• libexec_dirs (CCACHE_LIBEXEC_DIRS) — If set, ccache looks for helper programs in these directories instead of the default. Simple as that, no cap.
• log_file (CCACHE_LOGFILE) — If set to a file path, ccache writes info on what it's doing to that file. Super useful for tracking down problems (iykyk, debugging era). 🕵️‍♀️

If set to syslog, ccache logs using syslog() instead of to a file. If you use rsyslogd, you can add something like this to /etc/rsyslog.conf or a file in /etc/rsyslog.d:

# log ccache to file
:programname, isequal, "ccache"         /var/log/ccache
# remove from syslog
& ~

• max_files (CCACHE_MAXFILES) — Specifies the maximum number of files to keep in the cache. Use 0 for no limit (which is the default). See also CACHE SIZE MANAGEMENT.
• max_size (CCACHE_MAXSIZE) — Specifies the maximum size of the cache. Use 0 for no limit. The default value is 5GiB. Available suffixes: kB, MB, GB, TB (decimal) and KiB, MiB, GiB, TiB (binary). The default suffix is GiB. See also CACHE SIZE MANAGEMENT. 📦
• msvc_dep_prefix (CCACHE_MSVC_DEP_PREFIX) — Specifies the prefix of included files output for the MSVC compiler. The default prefix is “Note: including file:”. If you use a localized compiler, set this accordingly, okay? 💅
• msvc_utf8 (CCACHE_MSVC_UTF8) — This one adds /utf-8 to the msvc command line when executing the preprocessor, so filenames don't get garbled for non-ascii characters. Warning tho: this implicitly enables /validate-charset and treats the source code as utf-8, which may cause compilation errors if comments in your code have characters in the [128, 255] range for a given Windows system codepage — that results in an invalid utf-8 sequence. 😭 The default is true.
• namespace (CCACHE_NAMESPACE) — If set, the namespace string gets added to the hashed data for each compilation. This makes the associated cache entries logically separate from cache entries with other namespaces, but bestie they still share the same storage space. Cache entries can also be selectively removed from the local cache with the command line option --evict-namespace, potentially in combination with --evict-older-than.

For instance, if you use the same local cache for several disparate projects, you can use a unique namespace string for each one. That way you can remove cache entries that belong to a certain project if you stop working with that project. Clean girl aesthetic for your cache. 🧹✨

• path (CCACHE_PATH) — If set, ccache searches directories in this list when looking for the real compiler. If not set, ccache looks for the first executable matching the compiler name in the normal PATH that isn't a symbolic link to ccache itself.
• pch_external_checksum (CCACHE_PCH_EXTSUM or CCACHE_NOPCH_EXTSUM, see Boolean values above) — When this is set and ccache finds a precompiled header file, ccache looks for a file with the extension “.sum” added (e.g. “pre.h.gch.sum”), and if found, it hashes this file instead of the precompiled header itself — working around the performance penalty of hashing very large files. Big brain move fr fr. 🧠
• prefix_command (CCACHE_PREFIX) — Adds a list of prefixes (separated by space) to the command line that ccache uses when invoking the compiler. See also USING CCACHE WITH OTHER COMPILER WRAPPERS.
• prefix_command_cpp (CCACHE_PREFIX_CPP) — Adds a list of prefixes (separated by space) to the command line that ccache uses when invoking the preprocessor. Same vibe, preprocessor edition. 🦋
• read_only (CCACHE_READONLY or CCACHE_NOREADONLY, see Boolean values above) — If true, ccache attempts to use existing cached results, but will NOT add new results to any cache backend. Statistics counters will still be updated though, unless the stats option is set to false.

If you're doing this because your ccache directory is read-only, you need to set temporary_dir since ccache will fail to create temporary files otherwise. You may also want to set stats to false to make ccache not even try to update stats files. 🙈

• read_only_direct (CCACHE_READONLY_DIRECT or CCACHE_NOREADONLY_DIRECT, see Boolean values above) — Just like read_only except ccache will only try to retrieve results from the cache using the direct mode, not the preprocessor mode. See documentation for read_only regarding using a read-only ccache directory.
• recache (CCACHE_RECACHE or CCACHE_NORECACHE, see Boolean values above) — If true, ccache will not use any previously stored result. New results will still be cached, possibly overwriting any pre-existing results. Out with the old, in with the new 💅
• remote_only (CCACHE_REMOTE_ONLY or CCACHE_NOREMOTE_ONLY, see Boolean values above) — If true, ccache only uses remote storage. Default is false. Note that cache statistics counters will still be kept in the local cache directory unless stats is false. See also Storage interaction.
• remote_storage (CCACHE_REMOTE_STORAGE) — Specifies one or several storage backends (separated by whitespace) to query after checking the local cache (unless remote_only is true). See REMOTE STORAGE BACKENDS for docs on syntax and available backends.

Examples:

remote_storage = file:/shared/nfs/directory+`
remote_storage =
  file:///shared/nfs/one read-only
  file:///shared/nfs/two
remote_storage = file:///Z:/example/windows/folder
remote_storage = http://example.com/cache
remote_storage = redis://example.com

Note 👀 In previous ccache versions this option was called secondary_storage (CCACHE_SECONDARY_STORAGE), which can still be used as an alias.

• reshare (CCACHE_RESHARE or CCACHE_NORESHARE, see Boolean values above) — If true, ccache writes results to remote storage even for local storage cache hits. The default is false.
• response_file_format (CCACHE_RESPONSE_FILE_FORMAT) — Ccache normally guesses the response file format based on the compiler type. This option lets you force the response file quoting behavior, which is useful if the compiler supports both POSIX and Windows response file quoting. Possible values are:
  • auto — Guess one of the formats below based on the compiler type. This is the default.
  • posix — POSIX quoting behavior.
  • windows — Windows quoting behavior.
• safe_dirs (CCACHE_SAFE_DIRS) — A list of trusted directories for which directory-specific configuration files are allowed to set "unsafe options" (see Directory-specific configuration file). The default is empty.

Allowed list values: * matches any directory. An absolute path ending with /* matches any subdirectory (at any depth) under that path. An absolute path not ending in /* matches only that directory. 🔒

• sloppiness (CCACHE_SLOPPINESS) — Okay so by default, ccache tries to give as few false cache hits as possible. But sometimes you know things ccache can't take for granted, and this option lets you tell ccache to relax some checks to increase the hit rate. Available values (separated by whitespace or comma):
  • clang_index_store — Use case: Xcode projects with varying index store paths. Effect: Ignores the -index-store-path and -index-unit-output-path options when hashing. Trade-off: Index won't update correctly on cache hits.
  • file_stat_matches — Use case: When file content checking is too slow. Effect: Uses file timestamps instead of content for cache validation. Trade-off: May miss content changes with identical timestamps.
  • file_stat_matches_ctime — Use case: When controlling file timestamps manually. Effect: Ignores status change time when file_stat_matches is enabled. Trade-off: May miss some file system changes.
  • gcno_cwd — Use case: Code coverage builds in different directories. Effect: Ignores current directory when creating .gcno files (-ftest-coverage). Also disables hashing of the current working directory if -fprofile-abs-path is used. Trade-off: Directory information in coverage files may be incorrect.

Note 🫶 No effect with --coverage (it implies -fprofile-arcs).

• incbin — Use case: Projects using assembly .incbin directives. Effect: Allows caching files with .incbin directives. Trade-off: Won't detect changes to included binary files.
• include_file_ctime — Use case: Build systems that modify file timestamps frequently. Effect: Ignores file status change time when checking for recent modifications. Trade-off: May miss recent changes to source files.

• include_file_mtime — bestie, use this when your build system is out here touching file timestamps like it's a nervous habit.
  • Use case: Build systems that modify file timestamps frequently.
  • Effect: Ignores file modification time when checking for recent changes.
  • Trade-off: May miss recent modifications to source files. 😬
• ivfsoverlay — for the Xcode girlies mixing things up.
  • Use case: Xcode projects mixing Objective-C and Swift.
  • Effect: Ignores -ivfsoverlay virtual filesystem option.
  • Trade-off: May not detect VFS-related changes.
• locale — vibe check on your environment variables.
  • Use case: Builds in environments with varying locale settings.
  • Effect: Ignores locale environment variables (LANG, LC_ALL, LC_CTYPE, LC_MESSAGES).
  • Trade-off: Compiler warning messages may vary between cached and fresh builds.
• modules — clang modules girlies, this one's for you 💅
  • Use case: Clang builds using -fmodules or -fprebuilt-implicit-modules.
  • Effect: Allows caching when C++ modules are used.
  • Trade-off: May not detect changes in module internal state, or in implicitly built modules.
  • See C++ MODULES for details.
• pch_defines — precompiled header moment.
  • Use case: Projects with precompiled headers.
  • Effect: Relaxes checking of #define directives in precompiled headers.
  • Trade-off: May not detect some macro definition changes.
  • See PRECOMPILED HEADERS for details.
• random_seed — chaos but make it cacheable.
  • Use case: Builds with varying -frandom-seed values.
  • Effect: Ignores random seed values in compilation hash.
  • Trade-off: Builds may not be fully reproducible. 🙈
• system_headers — for systems whose headers just won't sit still.
  • Use case: Systems with frequently changing system headers.
  • Effect: Only tracks non-system headers in direct mode.
  • Trade-off: Won't detect system header changes that affect compilation.
  • Limitations: Only supported for GCC-like compilers (not MSVC). System headers are still checked in preprocessor mode.
  • See also ignore_headers_in_manifest.
• time_macros — for the __DATE__ girlies who literally do not care.
  • Use case: Code using time macros but values don't matter.
  • Effect: Ignores __DATE__, __TIME__, and __TIMESTAMP__ in source.
  • Trade-off: Time values in output will be from cached compilation.

---

stats (CCACHE_STATS or CCACHE_NOSTATS, see Boolean values above)

If true, ccache will update the statistics counters on each compilation. The default is true. If false, automatic cleanup will be disabled as well. ✨ (okay so turning stats off also turns off autocleanup, that's the tea, don't forget it)

stats_log (CCACHE_STATSLOG)

If set to a file path, ccache will write statistics counter updates to the specified file. This is useful for getting statistics for individual builds. To show a summary of the current stats log, use ccache --show-log-stats. 📊

Note Lines in the stats log starting with a hash sign (#) are comments.

temporary_dir (CCACHE_TEMPDIR)

This option specifies where ccache will put temporary files. The default is $XDG_RUNTIME_DIR/ccache-tmp (typically /run/user/<UID>/ccache-tmp) if XDG_RUNTIME_DIR is set and the directory exists, otherwise <cache_dir>/tmp.

Note In previous versions of ccache, CCACHE_TEMPDIR had to be on the same filesystem as the CCACHE_DIR path, but this requirement has been relaxed. 🎀

umask (CCACHE_UMASK)

This option (an octal integer) specifies the umask for files and directories in the cache directory. This is mostly useful when you wish to share your cache with other users. 🫶 (sharing is caring, fr fr)

---

🚫 Disabling ccache

To disable ccache completely for all invocations, set disable = true (CCACHE_DISABLE=1). You can also disable ccache for a certain source code file by adding the string ccache:disable in a comment in the first 4096 bytes of the file. In the latter case the Ccache disabled statistics counter will be increased. 💀

---

☁️ REMOTE STORAGE BACKENDS ☁️

The remote_storage option lets you configure ccache to use one or several remote storage backends. By default, the local cache directory located in cache_dir will be queried first and remote storage second, but remote_only can be set to true to disable local storage. Note that cache statistics counters will still be kept in the local cache directory — remote storage backends only store compilation results and manifests. no cap ✨

🧚 Storage helper process

ccache can spawn a long-lived local storage helper process (installed separately) to handle communication with the remote storage. Storage helpers keep remote connections up for efficiency and terminate after a while on inactivity. See Storage helpers at https://ccache.dev/storage-helpers.html for a list of known helpers.

The storage helper program is called ccache-storage-<scheme>, where <scheme> is the scheme part of a URL, e.g. https. The program can be placed in these locations (in priority order):

1. In a location specified by the helper property (see below).
2. In a libexec directory.
3. Next to the ccache executable.
4. In $PATH.

If the program is not found, ccache falls back to one of the builtin backends if available, otherwise ccache exits with an error. 😭

📝 Configuration syntax

A remote storage backend is specified by a URL and can be followed by a whitespace-separated list of properties (key=value) and custom attributes (@key=value). A missing =value is shorthand for setting the value to true. Values must be percent-encoded (see https://en.wikipedia.org/wiki/Percent-encoding) if they contain %, | or whitespace characters. For compatibility with older ccache versions, | characters are treated as spaces.

🎀 Properties

• data-timeout: Timeout for send/receive data transfer. Resets whenever data is received or can be sent. Default: 10s.
• helper: Override which storage helper to spawn (either a filename or a full path). This is mainly useful when developing or testing new helpers.
• idle-timeout: Timeout for the helper process to wait before exiting after client inactivity (0s: stay up indefinitely). Default: 10m.
• read-only: If true, only read from this backend, don't write. The default is false.
• request-timeout: Timeout for the whole request. Default: 1m.
• shards: A comma-separated list of names for sharding (partitioning) the cache entries using Rendezvous hashing (see https://en.wikipedia.org/wiki/Rendezvous_hashing), typically to spread the cache over a server cluster. When set, the storage URL must contain an asterisk (*), which will be replaced by one of the shard names to form a real URL. A shard name can optionally have an appended weight within parentheses to indicate how much of the key space should be associated with that shard. A shard with weight w will contain w/S of the cache, where S is the sum of all shard weights. A weight could for instance be set to represent the available memory for a memory cache on a specific server. The default weight is 1.

Examples:

• http://cache-*.example.com shards=a(3),b(1),c(1.5) will put 55% (3/5.5) of the cache on http://cache-a.example.com, 18% (1/5.5) on http://cache-b.example.com and 27% (1.5/5.5) on http://cache-c.example.com. 🔥
• http://example.com/* shards=alpha,beta will put 50% of the cache on http://example.com/alpha and 50% on http://example.com/beta.

Timeouts can be specified with an ms (milliseconds), s (seconds), m (minutes), h (hours) or d (days) suffix. ⏱️

💅 Custom attributes

Custom attributes on the form @key=value are specific to each storage helper implementation. See the backend's documentation for which attributes are available. Examples:

• file:///example/directory @umask=002 @update-mtime=true
• https://example.com/path @bearer-token=deadbeef

🔄 Storage interaction

The list below describes the interaction between local and remote storage on cache hits and misses if remote_only is false (which is the default):

• Local storage: miss, remote storage: miss → Compile, write to local, write to remote[1]
• Local storage: miss, remote storage: hit → Read from remote, write to local
• Local storage: hit, remote storage: - → Read from local, don't write to remote[2]

[1] Unless remote storage has property read-only=true.

[2] Unless local storage is set to share its cache hits with the reshare option. 👑

If remote_only is true, here's the whole mood 👇

• local: - (nothing), remote: miss — compile it, write it to remote, and do not write to local storage. Bestie, the local cache stays untouched, periodt.
• local: - (nothing), remote: hit — read it straight from remote, and again, don't write to local.

---

🌸 File storage backend 🌸

URL format: file:DIRECTORY or file://[HOST]DIRECTORY

This one stores data as separate files in a directory structure below DIRECTORY, which is similar to (but not identical to) the local cache storage, okurrr. A classic use case is sharing a cache on an NFS directory. DIRECTORY must start with a slash. HOST can be the empty string or localhost. On Windows, HOST can also be the name of a server hosting a shared folder. 🫶

⚠️ Important: ccache will not perform any cleanup of the storage — that has to be done by other means, for instance by running ccache --trim-dir periodically. So like, don't expect it to tidy up after itself, because it won't. 💀

Examples:

• file:/shared/nfs/directory
• file:///shared/nfs/directory @umask=002 @update-mtime=true
• file:///Z:/example/windows/folder
• file://example.com/shared/ccache%20folder

Optional attributes:

• @layout — how to store files under the cache directory. Available values:
  • flat — store all files directly under the cache directory.
  • local — read files using the dynamic directory layout of the local cache. This layout is intended for a one-way copy or read-only mount of a local cache directory, and it makes the file storage backend read-only. The directory must contain self-contained entries (file_clone or hard_link are not supported). 🚫
  • subdirs — store files in 256 subdirectories of the cache directory.
  • The default is subdirs.
• @umask — this attribute (an octal integer) overrides the umask to use for files and directories in the cache directory.
• @update-mtime — if true, update the modification time (mtime) of cache entries that are read. The default is false.

---

🧚 CRSH storage backend 🧚

URL format: crsh:IPC_ENDPOINT

This backend connects to an already-running ccache storage helper (CRSH) process that's listening on IPC_ENDPOINT (a Unix socket path or a Windows named pipe). The use case here is mainly when you're developing or debugging a storage helper, or in special setups where the helper program is started and managed externally. Very behind-the-scenes, very main character energy. ✨

Examples:

• crsh:/path/to/your.sock (Unix socket)
• crsh:name-of-your-pipe (Windows named pipe)

---

🎀 HTTP storage backend 🎀

🚨 Warning: Built-in support for the HTTP protocol is deprecated and will be removed in the next non-bug-fix ccache version. Use a remote storage helper instead. Like, it's giving end of an era. 😭

URL format: http://HOST[:PORT][/PATH]

This backend stores data in an HTTP-compatible server. The required HTTP methods are GET, PUT and DELETE. That's the whole bar to clear, ngl.

⚠️ Important: ccache will not perform any cleanup of the storage — that has to be done by other means, for instance by running ccache --trim-dir periodically.

📝 Note: HTTPS is not supported. I know. I know. 🙈

💡 Tip: See How to set up HTTP storage at https://ccache.dev/howto/http-storage.html for hints on how to set up an HTTP server for use with ccache.

Examples:

• http://localhost
• http://someusername:p4ssw0rd@example.com/cache/
• http://localhost:8080 @layout=bazel

Optional attributes:

• @bearer-token — bearer token used to authorize the HTTP requests.
• @keep-alive — if true, keep the HTTP connection to the storage server open to avoid reconnects. The default is true.
• @layout — how to map key names to the path part of the URL. Available values:
  • bazel — store values in a format compatible with the Bazel HTTP caching protocol. More specifically, the entries will be stored as 64 hex digits under the /ac/ part of the cache.

📝 Note: You may have to disable verification of action cache values in the server for this to work, since ccache entries are not valid action result metadata values. Yeah. Awkward. 💅

• flat — append the key directly to the path part of the URL (with a leading slash if needed).
• subdirs — append the first two characters of the key to the URL (with a leading slash if needed), followed by a slash and the rest of the key. This divides the entries into 256 buckets.
• The default is subdirs.

• @header — add the key=value pair to the HTTP headers of the request. For example: @header=Content-Type=application/octet-stream adds "Content-Type: application/octet-stream" to the HTTP headers of the request.

---

🍓 Redis storage backend 🍓

🚨 Warning: Built-in support for the Redis protocol is deprecated and will be removed in the next non-bug-fix ccache version. Use a remote storage helper instead.

URL formats:

redis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]
redis+unix:SOCKET_PATH[?db=DBNUMBER]
redis+unix://[[USERNAME:]PASSWORD@localhost]SOCKET_PATH[?db=DBNUMBER]

This backend stores data in a Redis (or Redis-compatible) server. There are implementations for both memory-based and disk-based storage. PORT defaults to 6379 and DBNUMBER defaults to 0. Slay. 🔥

📝 Note: ccache will not perform any cleanup of the Redis storage, but you can configure LRU eviction.

💡 Tip: See How to set up Redis storage at https://ccache.dev/howto/redis-storage.html for hints on setting up a Redis server for use with ccache.

💡 Tip: You can set up a cluster of Redis servers using the shards property described in REMOTE STORAGE BACKENDS.

Examples:

• redis://localhost
• redis://p4ssw0rd@cache.example.com:6379/0
• redis+unix:/run/redis.sock
• redis+unix:///run/redis.sock
• redis+unix://p4ssw0rd@localhost/run/redis.sock?db=0

---

💖 CACHE SIZE MANAGEMENT 💖

So by default, ccache has a 5 GB limit on the total size of files in the cache, and no limit on the number of files. You can set different limits using the command line options -M/--max-size and -F/--max-files. Use the -s/--show-stats option to see the cache size and the currently configured limits (in addition to other various statistics). Look at her go. 👑

Cleanup can be triggered in two different ways: automatic and manual.

🌈 Automatic cleanup 🌈

After a new compilation result has been stored in the local cache, ccache will trigger an automatic cleanup if max_size or max_files is exceeded. The cleanup removes cache entries in approximate LRU (least recently used) order, based on the modification time (mtime) of files in the cache. For this reason, ccache updates the mtime of the cache files read on a cache hit to mark them as recently used. It's literally keeping receipts of who was here last. 🕵️

For performance reasons, only entries in a subset of the cache are considered when automatic cleanup is triggered, so the oldest entries aren't always removed first — but the overall behavior approximates LRU over time. So it's vibes-based LRU, but the vibes are, like, correct on average. 😌

🦋 Manual cleanup 🦋

Run ccache --cleanup to force cleanup of the whole cache. This will recalculate the cache size information and make sure that the cache size does not exceed max_size and max_files.

Note that there is no guarantee that only the oldest entries are evicted, as discussed in Automatic cleanup above. To evict based on age, use ccache --evict-older-than AGE. That's the one you want if you're being picky about age. 💅

---

🔥 CACHE COMPRESSION 🔥

By default, ccache compresses all cached data using the Zstandard (zstd) algorithm at compression level 1. This algorithm is fast enough that compression rarely impacts performance. You might want to disable compression only if your cache is stored on an already-compressed filesystem, where ccache's compression would be redundant. Like wearing two jackets. 🧥🧥

For configuration details, see compression and compression_level.

Use ccache --show-compression to display compression information. Example output:

Total data:           14.8 GB (16.0 GB disk blocks)
Compressed data:      11.3 GB (30.6% of original size)
  Original size:      36.9 GB
  Compression ratio: 3.267 x  (69.4% space savings)
Incompressible data:   3.5 GB

Notes, bestie, take these in:

• Disk blocks — the actual cache size accounting for filesystem block size. This should match the "Cache size" from ccache --show-stats.
• Compressed data — result and manifest files stored in the cache.
• Incompressible data — files stored without compression (due to file_clone or hard_link settings) or legacy files from older ccache versions. Old money, basically. 🏛️
• Compression ratio — affected by compression_level.

You can recompress cached data to different compression levels using ccache --recompress. Only files with different compression levels than the target will be recompressed. No wasted effort, we love efficiency. ⭐

---

⭐ CACHE STATISTICS ⭐

ccache --show-stats shows a summary of statistics, including cache size, cleanups (number of performed cleanups, either implicitly due to a cache size limit being reached or due to explicit ccache -c calls), overall hit rate, hit rate for direct/preprocessed modes, and hit rate for local and remote storage. It's the whole story of your cache in one screen, and honestly? Iconic. 💜

Okay so real talk: those statistics counters? ccache itself literally does not touch them during builds. Like, not even a little. Which means you can safely reset them whenever you want with ccache --zero-stats and your build will not care at all — no cap, zero drama, the build process stays completely unaffected. 💅

Why would you even want to do that? Say you're about to run a build and you want ccache --show-stats to summarize only that specific build. Just zero the counters first and you're golden. ✨

Bestie tip: resetting is totally safe, but it does wipe the lifetime numbers — so pick your moment.

Orrrr, if you'd rather keep the lifetime stats intact, you can set stats_log before starting the build and then run ccache --show-log-stats afterward to peep build-specific statistics. 🎀 This approach is honestly kind of iconic: the statistics counters keep tracking the entire lifetime of the cache the whole time, and you still get detailed info for individual builds. Both. At once. Main character energy. 👑

And there's another advantage of stats_log too — it collects statistics without any interference from other concurrent builds that are accessing the same cache. 🦋 So if your machine is out here running multiple builds at the same time, your numbers stay clean and yours. Periodt. 💖

The summary also has “Errors” and “Uncacheable” counters, and bestie, those are literally just sums of the more detailed counters below 💅 so if you wanna see the receipts, just hit -v/--verbose and the verbose mode will spill all of these for you:

• Autoconf compile/link — an uncacheable compilation or linking done by an Autoconf test. like, the test was just vibing and ccache couldn't cache it 🫠
• Bad compiler arguments — malformed compiler argument, e.g. missing a value for a compiler option that requires an argument, or failure to read a file specified by a compiler option argument. the syntax was giving broken 💀
• Called for linking — the compiler was called for linking, not compiling. ccache only supports compilation of a single file, i.e. calling the compiler with the -c option to produce a single object file from a single source file. so yeah, we're not doing that linky thing ✨
• Called for preprocessing — the compiler was called for preprocessing, not compiling. respectfully, not our department 🙈
• Ccache disabled — ccache was disabled by a ccache:disable string in the source code file. the source file literally said "not me" 😭
• Could not use modules — the preconditions for using C++ MODULES were not fulfilled. modules said "i'm busy" 🎀
• Could not use precompiled header — the preconditions for using precompiled headers were not fulfilled. no precompiled header for you today, bestie 🌸
• Could not read or parse input file — an input file could not be read or parsed (see the debug log for details). the debug log is where the tea is ☕
• Could not write to output file — the output path specified with -o could not be written to. lowkey blocked 🚫
• Compilation failed — the compilation failed. no result stored in the cache. it flopped, and we do not cache flops 💀
• Compiler check failed — a compiler check program specified by compiler_check (CCACHE_COMPILERCHECK) failed. the vibe check did not pass 😔
• Compiler output file missing — one of the files expected to be produced by the compiler was missing after compilation. it was supposed to be there and then... wasn't 👻
• Compiler produced empty output — the compiler's output file (typically an object file) was empty after compilation. zero bytes, zero thoughts, head empty 🫶
• Could not find the compiler — the compiler to execute could not be found. where did it go. genuinely where 🧚
• Error hashing extra file — failure reading a file specified by extra_files_to_hash (CCACHE_EXTRAFILES). couldn't hash it, so we couldn't help it 😭
• Forced recache — CCACHE_RECACHE was used to overwrite an existing result. we said do it again and it ATE 🔥
• Input file modified during compilation — an input file was modified during compilation. rude, honestly, we were mid-compile 💅
• Internal error — unexpected failure, e.g. due to problems reading/writing the cache. the cache was acting up, iconic but not in a good way 💀
• Missing cache file — a file was unexpectedly missing from the cache. this only happens in rare situations, e.g. if one ccache instance is about to get a file from the cache while another instance removed the file as part of cache cleanup. so like, one girl was grabbing it while another girl was decluttering — tragic timing 😭
• Multiple source files — the compiler was called to compile multiple source files in one go. this is not supported by ccache. one at a time, we're not doing a group project 🙅‍♀️
• No input file — no input file was specified to the compiler. nothing to compile, babe. an empty plate 🍽️
• Output to stdout — the compiler was told to write its output to standard output with -o -. Ccache does not support this, sorry bestie.
• Preprocessing failed — preprocessing the source code with the compiler's -E option just... did not work.
• Unsupported code directive — something like the assembler .incbin directive showed up in the code. Ccache does not support that.
• Unsupported compiler option — a compiler option that ccache doesn't support got used.
• Unsupported environment variable — an environment variable that ccache doesn't support was set.
• Unsupported source encoding — the source file (or one of the included headers) has an encoding ccache can't deal with. Right now ccache needs UTF-8-encoded source code for MSVC when msvc_utf8 is true. That's the rule, no cap.
• Unsupported source language — a source language, like the one you'd set with -x, that ccache doesn't support.

---

✨ HOW CCACHE WORKS ✨

Okay so here's the whole vibe 💅 ccache peeps when you're compiling the same code twice and just reuses the output it already stashed. How? It builds a unique hash — the "input hash" — out of all the info that actually affects the compilation. Then when that exact same hash shows up again, ccache can hand you back all the correct compiler outputs straight from the cache. Iconic behaviour, honestly.

For the hashing itself, ccache uses BLAKE3 (the one at https://blake3.io), which is a fast cryptographic hash algorithm. And for data integrity, cached data is protected with XXH3 (over at https://xxhash.com) checksums so corruption gets caught. 🛡️

Ccache has two strategies for gathering the info that goes into cache lookup keys:

• Preprocessor mode — ccache runs the preprocessor on the source code and hashes the result.
• Direct mode — ccache hashes the source code and the include files directly.

Direct mode is generally faster because it skips the overhead of running the preprocessor. Speed queen behaviour. ⚡

When direct mode doesn't find a cached result (that's a cache miss, fyi), ccache falls back to preprocessor mode — unless depend mode is enabled. In depend mode, ccache never runs the preprocessor, not even on cache misses. See The depend mode below for the deets 🫶

🌸 Common hashed information 🌸

This info is always in the hash, every single time:

• the extension the compiler uses for a file with preprocessor output (normally .i for C code and .ii for C++ code)
• the compiler's size and modification time (or other compiler-specific info specified by compiler_check)
• the name of the compiler
• the current directory (if hash_dir is enabled)
• contents of files specified by extra_files_to_hash (if there are any)

🎀 The preprocessor mode 🎀

In preprocessor mode, the hash is made of the common info plus:

• the preprocessor output from running the compiler with -E
• the command line options, except the ones that affect include files (-I, -include, -D, etc. — the theory being that those command line options will change the preprocessor output if they have any effect at all)
• any standard error output the preprocessor generated

Based on that hash, the cached compilation result can be looked up directly in the cache. Easy. 💅

🦋 The direct mode 🦋

In direct mode, the hash is made of the common info plus:

• the input source file
• the compiler options

Based on that hash, ccache looks up a data structure in the cache called a "manifest". That manifest contains:

• references to cached compilation results (object file, dependency file, etc.) that previous compilations matching the hash produced
• paths to the include files that were read back when those compilation results got stored in the cache
• hash sums of the include files at the time those compilation results were stored in the cache

Then the current contents of the include files get hashed and compared against the manifest. Match? ccache already knows the result of the compilation, slay. No match? ccache falls back to running the preprocessor. The preprocessor output gets parsed to find which include files were read, and the paths plus hash sums of those include files get stored in the manifest alongside info about the compilation result that was produced.

Okay so there's a catch with direct mode 🙈 header files that the compiler did use get recorded, but header files that it did not use — but would have used if they'd existed — do not. To soften that problem, ccache records whether directories specified with -I and similar exist at the time of compilation, which handles most cases. Still, when ccache checks whether a result can be taken from the cache, it currently can't check with 100% accuracy whether the existence of a new header file should invalidate the result. In practice though, direct mode is safe to use in the absolute majority of cases. 💖

Direct mode gets disabled if any of these hold:

• direct_mode is false
• a modification time of one of the include files is too new (needed to avoid a race condition)
• a compiler option not supported by direct mode is used, for example:
  • a -Wp,* compiler option other than -Wp,-MD,<path>, -Wp,-MMD,<path>, -Wp,-D<macro[=defn]> or -Wp,-U<macro>
  • most uses of -Xpreprocessor
• the string __TIME__ is present in the source code

💜 The depend mode 💜

If depend mode is enabled, ccache will not use the preprocessor at all. The hash used to identify results in the cache is based on the direct mode hash described above, plus info about include files read from the dependency list generated by MSVC with /showIncludes, or the dependency file generated by other compilers with -MD or -MMD.

Advantages:

• The ccache overhead of a cache miss will be much smaller.
• Not running the preprocessor at all can be a good thing if compilation happens remotely, for instance when using distcc or similar — ccache then won't make potentially costly preprocessor calls on the local machine. 💫

Disadvantages:

• The cache hit rate will likely be lower, since any change to compiler options or source code makes the hash different. Compare that to the default setup, where ccache falls back to preprocessor mode, which is tolerant to some types of changes in compiler options and source code.
• If -MD is used, the manifest entries will include system header files too, which slows down cache hits slightly, just like using -MD slows down make. Same deal for MSVC with /showIncludes.
• If -MMD is used, the manifest entries will not include system header files, which means ccache will ignore changes in them. 😬

Depend mode gets disabled if any of these hold:

• depend_mode is false.
• The compiler is not generating dependencies using -MD or -MMD (for MSVC, /showIncludes is added automatically if the user didn't specify it).

---

⭐ HANDLING OF NEWLY CREATED SOURCE FILES ⭐

Okay so if the modification time (mtime) or status change time (ctime) of the source file — or of any of the include files — is equal to (or newer than) the time ccache was invoked, ccache disables caching completely. Yeah, all of it. This is a safety measure to avoid a race condition (see below). In practice it only bites you when you're on file systems with very low timestamp granularity. You can set sloppiness to include_file_ctime,include_file_mtime to opt out of the safety measure. 🧚

For reference, that race condition I mentioned consists of these events:

1. A source code file is read by ccache and added to the input hash.
2. The source code file is modified.
3. The compiler is executed and reads the modified source code.
4. Ccache stores the compiler output in the cache associated with the incorrect key (the one based on the unmodified source code). 💀

Not the vibe. Protect your timestamps, bestie. 🫶

🔍 CACHE DEBUGGING 🔍

okay so if you're sitting there like "why am I not getting cache hits, what is ccache even hashing??" — bestie, same. The answer: turn on debug mode via the config option debug, or by setting CCACHE_DEBUG in the environment. It's literally made for investigating why you don't get cache hits. Just know that performance will be reduced slightly, ngl. A little sacrifice 💅

When debug mode is on, ccache will create up to five additional files next to the object file:

• <objectfile>.<timestamp>.ccache-input-c — debug level 2. Binary input hashed by both the direct mode and the preprocessor mode. 🤝
• <objectfile>.<timestamp>.ccache-input-d — debug level 2. Binary input only hashed by the direct mode.
• <objectfile>.<timestamp>.ccache-input-p — debug level 2. Binary input only hashed by the preprocessor mode.
• <objectfile>.<timestamp>.ccache-input-text — debug level 2. Human-readable combined diffable text version of the three files above. This one's the ✨ icon ✨
• <objectfile>.<timestamp>.ccache-log — debug level 1. Log for this object file.

The timestamp format is:

<year><month><day>_<hour><minute><second>_<microsecond>

If you only need the log file (valid, honestly), set debug_level (environment variable CCACHE_DEBUGLEVEL) to 1.

And if debug_dir (environment variable CCACHE_DEBUGDIR) is set, the files above will be written to that directory with full absolute paths instead of next to the object file. Slay, organized.

Okay so here's the hashing tea ☕ In the direct mode, ccache uses the 160 bit BLAKE3 hash of the "ccache-input-c" + "ccache-input-d" data (where + means concatenation), while the "ccache-input-c" + "ccache-input-p" data is used in the preprocessor mode.

The "ccache-input-text" file is a combined text version of the three binary input files. It has three sections ("COMMON", "DIRECT MODE" and "PREPROCESSOR MODE"), which in turn contain annotations that say what kind of data comes next. Fr fr, it's giving annotated anthology.

To debug why you don't get an expected cache hit for an object file, you can do something like this:

1. Enable debug (CCACHE_DEBUG).
2. Build.
3. Clean and build again.
4. Compare the <objectfile>.<timestamp>.ccache-input-text files for the two builds. This together with the <objectfile>.<timestamp>.ccache-log files should give you some clues about what is happening.

That's the whole ritual. Detective era 🔎

---

📁 COMPILING IN DIFFERENT DIRECTORIES 📁

When compiling the same source code in different directories, ccache often can't share cached results if absolute paths become part of the input hash. Tragic, I know 😭 These paths appear in:

• preprocessed source code (when using -g for debug info or absolute paths in -I options)
• command-line arguments (absolute paths to source files or include directories)
• macro expansions (__FILE__ macros and preprocessor warnings)

To enable cache sharing across different build directories for debug builds (using -g), normalize debug paths, e.g. with GCC option -fdebug-prefix-map=$PWD=. (map current directory to relative) or -fdebug-compilation-dir=. (set compilation directory). Alternatively, set hash_dir to false (disables directory hashing).

For builds with absolute paths, set base_dir to a common parent directory. Ccache will convert absolute paths under this directory to relative paths before hashing. Big brain move 🧠✨

For example, if projects are in /home/user/projects, set base_dir to /home/user/projects or just /home/user.

---

🧚 PRECOMPILED HEADERS 🧚

Ccache has limited support for precompiled headers (PCH) with GCC and Clang. Limited! Read the fine print bestie, don't come for me.

Required configuration:

1. Set sloppiness to pch_defines,time_macros
   • This is needed because ccache can't detect time macro usage or #define changes when using PCH.
   • Consider adding include_file_mtime,include_file_ctime for newly created files (see HANDLING OF NEWLY CREATED SOURCE FILES).
2. One of:
   • GCC/Clang: Use -include header (don't use #include in source; the filename must be sufficient to find the header).
   • Clang only: Use -include-pch with the generated PCH file.
   • GCC only: Add -fpch-preprocess when compiling.
3. For Clang, add -fno-pch-timestamp to disable timestamp checks.

Troubleshooting (aka when it goes sideways 🙈):

• Without proper setup, ccache falls back to the non-precompiled header (if available).
• If no fallback exists, you'll see "Preprocessing failed" in statistics.
• Files using #pragma once instead of include guards may cause issues.

---

💜 C++ MODULES 💜

Ccache does currently not support standard C++20 modules. Say it with me: no cap, not supported.

There is however limited support for "Clang modules" (the -fmodules option) with these requirements:

• Set sloppiness to modules.
• Enable both direct mode and depend mode.

This is how it works:

• Ccache hashes module.modulemap files but ignores Clang's binary module cache.
• This works because identical module.modulemap files should produce compatible cached results.

Note The preprocessor mode doesn't provide enough information for module support depend mode. When using the preprocessor mode Clang does not provide enough information to allow hashing of module.modulemap files. 💀

🌈 Explicit module files 🌈

Regardless of the above, ccache hashes the module files that a compilation reads, so that a consumer is recompiled when a module it imports changes. This works for the options that tell ccache which files those are:

• -fmodule-file=, which gives the path directly.
• -fprebuilt-module-path=, whose directory Clang searches for <module-name>.pcm. The command line doesn't say which of those files the compilation reads, so all of them are hashed, names as well as contents. This costs a hit when an unrelated module file in the same directory changes. Annoying but honest 🫠

-fprebuilt-implicit-modules compilations are counted as "Could not use modules" unless sloppiness is set to modules. Clang looks up implicit modules in a subdirectory layout named by hashes of compiler internals, so ccache can't tell which files the compilation reads.

---

🫶 SHARING A LOCAL CACHE 🫶

A group of developers can increase the cache hit rate by sharing a local cache directory. Bestie group project energy 👑 To share a local cache without unpleasant side effects, the following conditions should to be met:

• Use the same cache directory.
• Make sure that the configuration option hard_link is false (which is the default).
• Make sure that all users are in the same group.
• Set the configuration option umask to 002. This ensures that cached files are accessible to everyone in the group.
• Make sure that all users have write permission in the entire cache directory (and that you trust all users of the shared cache).
• Make sure that the setgid bit is set on all directories in the cache. This tells the filesystem to inherit group ownership for new directories. The following command might be useful for this:

find $CCACHE_DIR -type d | xargs chmod g+s

The reason to avoid the hard link mode is that the hard links cause unwanted side effects, as all links to a cached file share the file's modification timestamp. This results in false dependencies to be triggered by timestamp-based build systems whenever another user links to an existing file. Typically, users will see that their libraries and binaries are relinked without reason. Not the vibe 😤

You may also want to make sure that a base directory is set appropriately, as discussed in a previous section.

🌐 SHARING A CACHE ON NFS 🌐

Okay so you can put the cache directory on an NFS filesystem (or a similar filesystem), but bestie, keep these in mind first:

• Having the cache on NFS may slow down compilation. Do some benchmarking to see if it's even worth it, fr.
• Ccache hasn't been tested very thoroughly on NFS. Just so you know what you're walking into. 💀

A tip: set temporary_dir to a directory on the local host so temporary files don't generate NFS traffic. Chef's kiss move. ✨

It is recommended to use the same operating system version when using a shared cache. If the operating system versions are different then system include files will likely be different, and there'll be few or no cache hits between the systems. One way of improving the cache hit rate in that case is to set sloppiness to system_headers to ignore system headers. 🎀

An alternative to putting the main cache directory on NFS? Set up a remote storage file cache. Iconic. 👑

---

🫶 USING CCACHE WITH OTHER COMPILER WRAPPERS 🫶

The recommended way of combining ccache with another compiler wrapper (such as "distcc") is by letting ccache execute the compiler wrapper. Yes, ccache is the main character here. 💅

You do this by defining prefix_command, for example by setting the environment variable CCACHE_PREFIX to the name of the wrapper (e.g. distcc). Ccache will then prefix the command line with the specified command when running the compiler. And if you want to specify several prefix commands, set prefix_command to a space-separated list of commands.

Unless you set compiler_check to a suitable command (peep the description of that configuration option), it is not recommended to use the form ccache anotherwrapper compiler args as the compilation command. It's also not recommended to use the masquerading technique for the other compiler wrapper. The reason is that by default, ccache will in both cases hash the mtime and size of the other wrapper instead of the real compiler, which means that:

• Compiler upgrades will not be detected properly. 😭
• The cached results will not be shared between compilations with and without the other wrapper.

Another minor thing: if prefix_command is used, ccache will not invoke the other wrapper when running the preprocessor, which increases performance. You can use prefix_command_cpp if you also want to invoke the other wrapper when doing preprocessing (normally by adding -E). 🦋

---

⚠️ CAVEATS ⚠️

• The direct mode fails to pick up new header files in some rare scenarios. See The direct mode above. 🙈

---

🩺 TROUBLESHOOTING 🩺

General

To understand what ccache is doing you can enable debug logging by setting debug to true or using the environment variable CCACHE_DEBUG=1. See CACHE DEBUGGING for details. 🔍

You can also use ccache -s to view cache hit rates, miss reasons and other performance metrics. Literally your new best friend.

Performance

Ccache is designed to work well with minimal configuration, but you can optimize performance further: 🚀

• Place the cache directory on fast storage (SSD preferred).
• Ensure sufficient RAM so cached files stay in the filesystem cache.
• Consider using remote storage for sharing the cache.

To monitor cache effectiveness, compare ccache -s output before and after builds to identify issues.

If "preprocessed cache hits" increases instead of "direct cache hits", ccache is falling back to the slower preprocessor mode. Causes include:

• source code changes that don't affect preprocessor output
• changes to include-related options (-I, -include, -D) that don't change the actual preprocessed code
• using unsupported preprocessor options like -Xpreprocessor or -Wp,* (except -Wp,-MD,<path>, -Wp,-MMD,<path>, -Wp,-D<define>)
• first compilation after changing base_dir
• include files with timestamps newer than ccache startup (see HANDLING OF NEWLY CREATED SOURCE FILES)
• code containing __TIME__, __DATE__, or __TIMESTAMP__ forces preprocessor mode (if these macros aren't actually used or you don't need current values, set sloppiness to time_macros)
• input file path changes (affects __FILE__ macro expansion)

If identical code doesn't produce cache hits, these are some possible causes: 🌸

• time/date macros or generated code with timestamps/build counters
• cache cleanup due to size limits
• environment differences affecting compilation

Common error counters:

• "Multiple source files": The compiler was called with multiple source files at once (not supported by ccache).
• "Unsupported compiler option": Enable debug logging to see which option was rejected.
• "Preprocessing failed": Could indicate precompiled header issues (see PRECOMPILED HEADERS).
• "Could not use precompiled header": See PRECOMPILED HEADERS for setup requirements.
• "Could not use modules": See C++ MODULES for configuration needs and check which compiler option was rejected.

Corrupt object files

It should be noted that ccache is susceptible to general storage problems. If a bad object file sneaks into the cache for some reason, it will of course stay bad. Some possible reasons for erroneous object files are bad hardware (disk drive, disk controller, memory, etc), buggy drivers or file systems, a bad prefix_command or compiler wrapper. If this happens, the easiest way of fixing it is this:

1. Build so that the bad object file ends up in the build tree.
2. Remove the bad object file from the build tree.
3. Rebuild with CCACHE_RECACHE set.

An alternative is to clear the whole cache with ccache -C if you don't mind losing other cached results. 🫣

There are no reported issues about ccache producing broken object files reproducibly. That doesn't mean it can't happen, so if you find a repeatable case, please report it! We wanna know. 💖

---

📚 MORE INFORMATION 📚

Credits, mailing list information, bug reporting instructions, source code, etc, can be found on ccache's web site: https://ccache.dev.

---

👑 AUTHOR 👑

Ccache was originally written by Andrew Tridgell and is currently developed and maintained by Joel Rosdahl. See AUTHORS.txt or AUTHORS.html and https://ccache.dev/credits.html for a list of contributors. Legends, all of them. 🫡

---

And that's a wrap on the whole page, bestie!! 🎉 This was Ccache 4.14.1, dated 2026-10-04 — go forth and have a slay build, mwah 💋✨🦋