Does buildkit respect the compression-level supplied in the --output parameter?

[ivonindza]

I tried benchmarking the compression times of different zstd levels via buildkit and via the zstd binary and I get very different results. For example, for some higher levels, buildkit would finish building and pushing the image much faster than zstd can just compress it, and the image ends up being larger than the one compressed with the zstd binary, which leads me to believe that it does not in fact respect the supplied value. It looks to me as if buildkit uses only a few distinct levels and maps zstd levels 1-22 to these internal levels. E.g. the compression times and image sizes for levels 9-22 look pretty much identical. Can someone shed some light on this?

[polarathene]

Can someone shed some light on this?

Your insights are correct, compression-level is mapped to 4 compression levels from klauspost/compress/zstd (Zstd Go implementation):

compression-level	klauspost/compress/zstd level	Approx zstd compression level
0-2	Fastest	1
3-6 (default)	Default	3
7-8	Better	7
9+	Best	11

• klauspost/compress/zstd has expressed in Sep 2025 that there is no intent to add more than those 4 levels.
• The Docker docs on compression + compression-level disclose the compression libraries used, but without documenting the actual mapped ranges for compression-level (while no disclosure is provided within the buildkit docs).
• There is this tracking issue for potentially supporting zstd via CGO or an external command rather than the pure Go implementation used currently. Presumably compression and decompression performance may be better, along with the ability for more flexibility in compression speed/ratio.

---

Original reply

Just to clarify:

• If your image used a base layer and it was the a large size of the image size that would not be affected by compression unless you use force-compression=true to recompress third-party layers. So gzip layers would remain as gzip too.
• I've also read about cache hits for layers resulting in skipping a layer from being compressed again, which if not obvious may be a bit misleading. You've mentioned observing size differences for some levels so this doesn't seem to be an issue.

The support for compression-level was contributed some time ago (Feb 2022), but this seems to confirm your suspicions:

func toZstdEncoderLevel(level int) zstd.EncoderLevel {
    // map zstd compression levels to go-zstd levels
    // once we also have c based implementation move this to helper pkg
    if level < 0 {
        return zstd.SpeedDefault
    } else if level < 3 {
        return zstd.SpeedFastest
    } else if level < 7 {
        return zstd.SpeedDefault
    } else if level < 9 {
        return zstd.SpeedBetterCompression
    }

    return zstd.SpeedBestCompression
}

This logic could have been avoided by just passing the compression-level value to the library helper method EncoderLevelFromZstd() that maps to the library's approximate zstd level:

// EncoderLevelFromZstd will return an encoder level that closest matches the compression
// ratio of a specific zstd compression level.
// Many input values will provide the same compression level.
func EncoderLevelFromZstd(level int) EncoderLevel {
  switch {
    case level < 3:
      return SpeedFastest
    case level >= 3 && level < 6:
      return SpeedDefault
    case level >= 6 && level < 10:
      return SpeedBetterCompression
    default:
      return SpeedBestCompression
  }
}

---

UPDATE: That method got relocated here as of current master branch, so this logic remains the same.

Despite the go-zstd comment this is from the klauspost/compress/zstd package, which documents those levels and their expected equivalent mappings:

For now, a high speed (fastest) and medium-fast (default) compressor has been implemented.

• The "Fastest" compression ratio is roughly equivalent to zstd level 1.
• The "Default" compression ratio is roughly equivalent to zstd level 3 (default).
• The "Better" compression ratio is roughly equivalent to zstd level 7.
• The "Best" compression ratio is roughly equivalent to zstd level 11.

Better and Best levels were added Dec 2020, no change in the documented mapping since so they may no longer reflect their equivalent zstd levels compression ratio today.

---

I've filed an issue at the Docker docs repo to try make this information easier to discover 👍

[ivonindza]

That explains my observations. Thanks for digging into this issue 🙏