What Is the Default Compression Level for Zstd? A Complete Guide to ZSTD_CLEVEL_DEFAULT

Zstandard (zstd) uses compression level 3 as its default, defined by the ZSTD_CLEVEL_DEFAULT constant in the source code.

The facebook/zstd repository offers 22 regular compression levels plus negative "fast" modes, but knowing the default compression level for zstd is critical for production tuning. Level 3 provides a balanced trade-off between speed and compression ratio, serving as the baseline when no specific level is requested via the CLI or C API.

What Is the Default Compression Level for Zstd?

The default compression level for zstd is level 3. This value is hardcoded as ZSTD_CLEVEL_DEFAULT in lib/zstd.h at lines 133–134. When you run the zstd command without flags or call ZSTD_compress() with level 0, the algorithm automatically selects level 3.

Level 3 is chosen because it offers strong compression ratios with high throughput, making it suitable for general-purpose workloads. The constant ZSTD_CLEVEL_DEFAULT ensures consistent behavior across the CLI and all language bindings that wrap the core C library.

The Full Spectrum of Zstd Compression Levels

Zstd exposes a flexible range of compression strategies that span from ultra-fast to maximum compression. These levels are defined in lib/compress/clevels.h, which contains static parameter tables for different source-size regimes.

Regular Levels (1–22)

Standard compression levels range from 1 to 22, where higher numbers yield better compression at the cost of speed and memory. The maximum level is exposed by the macro ZSTD_MAX_CLEVEL (value 22) in lib/zstd.h. The concrete parameter sets for each level live in the static tables in lib/compress/clevels.h at lines 25–50, which cover different source-size regimes including large files, ≤256 KB, ≤128 KB, and ≤16 KB buffers.

Fast Levels (Negative Values)

For speed-critical applications, zstd provides negative compression levels accessed via the --fast=# CLI flag. Internally, these use the ZSTD_fast strategy. If the =# argument is omitted, the default fast level is 1. These negative levels are defined as the base for negative levels in lib/compress/clevels.h at lines 28–31.

Ultra Levels (20–22)

Levels 20 through 22 are designated as "ultra" modes that consume significantly more memory but achieve the strongest compression ratios. These require explicit enablement with the --ultra or --max flag in the CLI. The parameters for these levels are stored in the same tables in lib/compress/clevels.h at lines 45–50.

How to Configure Compression Levels

You can specify compression levels through both the command-line interface and the C API.

Command-Line Usage

# Default compression (level 3)

zstd file.txt

# Fast mode – level 1 (ultra‑fast)

zstd --fast=1 file.txt

# Fast mode – level 4 (even faster)

zstd --fast=4 file.txt

# Regular level 9

zstd -9 file.txt

# Ultra‑high level 22 (max compression, high memory)

zstd --ultra -22 file.txt

Using the C API

#include <zstd.h>

/* Prepare source data */
const void* src = ...;
size_t srcSize = ...;

/* Allocate destination buffer (worst‑case size) */
size_t bound = ZSTD_compressBound(srcSize);
void* dst = malloc(bound);

/* Choose a compression level (e.g., 15) */
int cLevel = 15;                     /* 1‑22 for regular levels, negative for fast */
size_t compressedSize = ZSTD_compress(dst, bound, src, srcSize, cLevel);
if (ZSTD_isError(compressedSize)) {
    fprintf(stderr, "compression error: %s\n", ZSTD_getErrorName(compressedSize));
}

/* Query the maximum available level */
int maxLevel = ZSTD_maxCLevel();     /* Returns 22, implemented in lib/compress/zstd_compress.c */

/* Decompress */
void* out = malloc(srcSize);
size_t decompressedSize = ZSTD_decompress(out, srcSize, dst, compressedSize);

Summary

• The default compression level for zstd is 3, defined by ZSTD_CLEVEL_DEFAULT in lib/zstd.h.
• Passing level 0 to the API or CLI defers to this default.
• Regular levels span 1–22, with ZSTD_MAX_CLEVEL (22) defined in lib/zstd.h and parameter tables in lib/compress/clevels.h.
• Negative levels provide ultra-fast compression via the ZSTD_fast strategy and are accessed using --fast=#.
• Ultra levels 20–22 require the --ultra flag and offer maximum compression at the cost of memory.
• Call ZSTD_maxCLevel() in lib/compress/zstd_compress.c to programmatically retrieve the highest supported level.

Frequently Asked Questions

What is the default compression level for zstd?

Zstd uses level 3 as its default compression level. This is specified by the ZSTD_CLEVEL_DEFAULT macro in lib/zstd.h. When you compress data without specifying a level, or explicitly pass level 0, the algorithm uses this preset to balance speed and compression efficiency.

What is the maximum compression level available in zstd?

The maximum regular compression level is 22, defined by ZSTD_MAX_CLEVEL in lib/zstd.h. You can query this value at runtime using the ZSTD_maxCLevel() function implemented in lib/compress/zstd_compress.c. Levels 20–22 are considered "ultra" modes and require additional memory.

How do negative compression levels work in zstd?

Negative compression levels represent ultra-fast modes that prioritize speed over compression ratio. These levels use the ZSTD_fast strategy and are accessed via the --fast=# CLI flag or by passing negative integers to the C API. The default fast level is 1 if no number is specified, and these parameters are defined in lib/compress/clevels.h.

What does compression level 0 mean in zstd?

Compression level 0 is a special value that tells zstd to use the default level (3). This is handled in the CLI and API as a convenience alias, ensuring that explicitly requesting level 0 produces the same output as omitting the level parameter entirely.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}