Search Zstandard Files with zstdgrep Without Decompressing Them First

You will search .zst files with ordinary grep patterns while leaving the compressed files unchanged. The installed command is zstdgrep from zstd 1.5.6, and its man page describes it as a small wrapper that decompresses through zstdcat before running grep.

Allow about ten minutes. You need a shell, the zstdgrep command and read access to the input files. These examples only read data and print matches; they do not need elevated privileges.

1. Check the command before searching

Confirm which executable your shell will run and record its version:

$ command -v zstdgrep
/usr/bin/zstdgrep
$ zstdgrep --version
zstd 1.5.6

The version output is supplied by the installed zstd tools. Option support belongs to both zstdgrep and the grep implementation it calls, so check the local grep manual when you need a less familiar grep feature.

Checkpoint: if command -v prints nothing, stop and install or enable the zstd package through your normal system-management process. Do not compensate by running an unknown copy from the current directory.

2. Search one compressed file

Put the pattern first and the compressed file afterwards:

$ zstdgrep 'ERROR' /var/log/example.log.zst
2026-09-28T08:14:22Z ERROR connection refused

The pattern and the remaining arguments are passed to grep. Quoting the pattern is a safe default: it prevents the shell from treating characters such as *, $ or spaces as shell syntax before grep receives them.

zstdgrep does not rewrite the input. It reads the compressed stream, decompresses it for the search, and sends matching lines to standard output. If the source is unreadable or not a valid zstd stream, expect an error from zstd rather than a match.

3. Search several files and keep their names

Pass more than one file when the question spans a set of archives:

$ zstdgrep 'timeout' /var/log/app-2026-09-27.log.zst /var/log/app-2026-09-28.log.zst
/var/log/app-2026-09-27.log.zst:2026-09-27T19:03:11Z timeout waiting for database
/var/log/app-2026-09-28.log.zst:2026-09-28T07:42:09Z timeout waiting for database

grep normally prefixes each matching line with the file name when it receives multiple files. If you add a grep option that changes that display, the output will change too. Treat the result as text for a human review unless you have deliberately chosen a machine-readable format.

Do not use an unquoted wildcard casually. The shell expands /var/log/app-*.zst before zstdgrep starts, and a large or unexpected set of files can make a search slow or exceed the command line length limit. Inspect the expansion first when the directory is busy:

$ printf '%s\n' /var/log/app-*.zst

4. Use grep flags through zstdgrep

zstdgrep accepts grep flags before the pattern. For example, -n prints line numbers and -i makes a case-insensitive search:

$ zstdgrep -n -i 'warning' /var/log/example.log.zst
18:2026-09-28T08:14:22Z Warning: retrying request

If the pattern begins with a hyphen, use the documented separator so grep does not mistake it for another option:

$ zstdgrep -n -- '-deprecated' /var/log/example.log.zst

There is another precise form for patterns that need to be supplied as an option. With -e, zstdgrep stops looking for a separate pattern argument and passes the expression to grep:

$ zstdgrep -n -e 'failed|refused' /var/log/example.log.zst

The exact regular-expression language is grep's, not a zstdgrep-specific language. Check man grep before using extended expressions, fixed-string mode or output-control flags in a script.

5. Search standard input

When there is no file argument, zstdgrep reads standard input. This is useful when another command has already produced decompressed text:

$ zstdcat /var/log/example.log.zst | zstdgrep -n 'ERROR'
42:2026-09-28T08:14:22Z ERROR connection refused

For a normal compressed file, prefer giving that file directly to zstdgrep. The pipeline above is still useful when the input is coming from another source or when you need an earlier transformation. Do not decompress to a temporary file merely to search it unless you have a reason to retain that uncompressed copy.

6. Check the result status before scripting around it

Capture the status immediately if a script needs to distinguish a match from a failed search:

if zstdgrep -q 'ERROR' /var/log/example.log.zst; then
    printf '%s\n' 'An error was found'
else
    status=$?
    case "$status" in
        1) printf '%s\n' 'No match, or the pattern/file was missing' ;;
        *) printf 'Search failed with status %s\n' "$status" >&2; exit "$status" ;;
    esac
fi

On the installed command, a matching search returned 0, while a search with no matches returned 1. The man page also documents status 1 for missing arguments or a missing pattern. A missing input file produced a zstd diagnostic and status 1 in testing, so do not treat every 1 as proof that the archive was successfully searched and simply had no match.

The example uses -q so a monitoring check does not print matching lines. Remove -q when you need the lines themselves. The status must be saved before another command overwrites $?.

7. Avoid the common traps

• zstdgrep is for zstandard-compressed input. A file ending in .zst is only a naming convention; malformed or differently compressed data will fail.
• Do not put the file name before the pattern. The synopsis is zstdgrep [grep-flags] [--] pattern [files ...].
• Do not assume every grep extension has identical syntax across systems. zstdgrep passes arguments to the local grep.
• Do not use sudo as a routine fix. Use elevated privileges only when the file permissions genuinely require them, and consider whether the resulting log data should be exposed to your account first.
• Modern grep alternatives, including ripgrep on systems where its zstd support is enabled, may be better for complex searches. Their command-line details are not necessarily the same as zstdgrep's.