ccache(1)

Clean up the cache by removing not recently used cached files until the specified file number and cache size limits are not exceeded. This also recalculates the cache file count and size totals. Normally, there is no need to initiate cleanup manually as ccache keeps the cache below the specified limits at runtime and keeps statistics up to date on each compilation. Forcing a cleanup is mostly useful if you have modified the cache contents manually or believe that the cache size statistics may be inaccurate.

Clear the entire cache, removing all cached files, but keeping the configuration file.

Let the command line options operate on configuration file PATH instead of the default. Using this option has the same effect as setting (overriding) the environment variable CCACHE_CONFIGPATH temporarily.

Let the command line options operate on cache directory PATH instead of the default. For example, to show statistics for a cache directory at /shared/ccache you can run ccache -d /shared/ccache -s. Using this option has the same effect as setting the environment variable CCACHE_DIR temporarily.

Remove files created in the given namespace from the cache.

Remove files used less recently than AGE from the cache. AGE should be an unsigned integer with a d (days) or s (seconds) suffix. If combined with --evict-namespace, only remove files within that namespace.

Print a summary of command line options.

Set the maximum number of files allowed in the cache to NUM. Use 0 for no limit. The value is stored in a configuration file in the cache directory and applies to all future compilations.

Set 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). The 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.

Recompress 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 information. This can potentially take a long time since all files in the cache need to be visited. Only files that are currently compressed with a different level than LEVEL will be recompressed.

Use up to THREADS threads when recompressing the cache. The default is to use one thread per CPU.

Set configuration option KEY to VALUE in the configuration file. See Configuration for more information.

Print cache compression statistics. See Cache compression for more information. This can potentially take a long time since all files in the cache need to be visited.

Print current configuration options and from where they originate (environment variable, configuration file or compile-time default) in human-readable format.

Print statistics counters from the stats log in human-readable format. See stats_log. Use -v/--verbose once or twice for more details.

Print a summary of configuration and statistics counters in human-readable format. Use -v/--verbose once or twice for more details.

Increase verbosity. The option can be given multiple times.

Print version and copyright information.

Zero the cache statistics (but not the configuration options).

Remove not recently used files from directory PATH until it is at most the size specified by --trim-max-size.

Specify 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.

Specify the method to trim a directory with --trim-dir. Possible values are:

Recompress 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 information. This can potentially take a long time since all files in the cache need to be visited. Only files that are currently compressed with a different level than LEVEL will be recompressed.

Recompress using up to THREADS threads with --trim-recompress. The default is to use one thread per CPU.

Print the checksum (128 bit XXH3) of the file at PATH (- for standard input).

Extract data stored in the result file at PATH (- for standard input). The data will be written to ccache-result.* files in to the current working directory. This option is only useful when debugging ccache and its behavior.

Specify format for --print-log-stats and --print-stats. Possible values are:

Print the value of configuration option KEY. See Configuration for more information.

Print the hash (160 bit BLAKE3) of the file at PATH (- for standard input). This is only useful when debugging ccache and its behavior.

Print 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 statistics counters from the stats log in machine-parsable (tab-separated or JSON) format. See stats_log and --format.

Print statistics counter IDs and corresponding values in machine-parsable (tab-separated or JSON) format. See --format.

Print version and don’t do anything else.

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.

This option should be an absolute path to a directory. If set, ccache will rewrite absolute paths into paths relative to the current working directory, but only absolute paths that begin with base_dir. Cache results can then be shared for compilations in different directories even if the project uses absolute paths in the compiler command line. See also the discussion under Compiling in different directories. If set to the empty string (which is the default), no rewriting is done.

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

# 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 /home/alice:
gcc -I/usr/include/example -I../../project2/include -c ../src/example.c

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

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

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

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

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.

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: