tar --zstd: zstd Compression (Usage & CI Errors)
tar --zstd pipes the archive through zstd, the fast modern compressor.
zstd is the workhorse of modern CI caches: near-gzip ratios at a fraction of the time, with tunable levels. The GitHub Actions cache uses it when zstd is available on the runner.
What it does
tar --zstd runs the archive through zstd on create and zstd -d on extract, producing or reading a .tar.zst. It is far faster than xz at comparable ratios, which is why cache tooling prefers it. Support requires a reasonably modern tar (GNU tar 1.31+) or the -I "zstd" form on older builds.
Common usage
tar --zstd -cf out.tar.zst dir/
tar --zstd -xf out.tar.zst
tar -I 'zstd -19 -T0' -cf out.tar.zst dir/ # older tar, level 19, threads
ZSTD_CLEVEL=19 tar --zstd -cf out.tar.zst dir/Options
| Flag | What it does |
|---|---|
| --zstd | Filter through zstd (GNU tar 1.31+) |
| -I "zstd" | Use zstd as a custom compressor on older tar |
| -I "zstd -19 -T0" | Set level and thread count |
| ZSTD_CLEVEL env var | Default compression level for zstd |
In CI
The actions/cache toolkit tars the cached paths and compresses with zstd when it is on the PATH, falling back to gzip otherwise. A cache saved on a zstd runner and restored on one without zstd can fail to decompress, which is why the cache key and tool versions should be consistent across jobs.
Common errors in CI
tar: Cannot use compressed or remote archives or tar: unrecognized option --zstd means the tar is too old; use -I "zstd" instead. tar (child): zstd: Cannot exec: No such file or directory means the zstd binary is missing; install the zstd package. zstd: error 70 : Write error : No space left on device is a full-disk error, not a format error.