---
name: "mkuzip"
section: "8"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/mkuzip"
---

# mkuzip(8)

compress disk image for use with geom\_uzip(4) class

## NAME

**mkuzip** – compress disk image for use with [geom\_uzip(4)](/geom_uzip/4.md) class

## SYNOPSIS

**mkuzip** \[**-dSsvZ**\] \[**-A** *compression\_algorithm*\] \[**-C** *compression\_level*\] \[**-j** *compression\_jobs*\] \[**-o** *outfile*\] \[**-s** *cluster\_size*\] *infile*

## DESCRIPTION

The **mkuzip** utility compresses a disk image file so that the [geom\_uzip(4)](/geom_uzip/4.md) class will be able to decompress the resulting image at run-time. This allows for a significant reduction of size of disk image at the expense of some CPU time required to decompress the data each time it is read. The **mkuzip** utility works in two phases:

1. An *infile* image is split into clusters; each cluster is compressed.

2. The resulting set of compressed clusters is written to the output file. In addition, a “table of contents” header is written which allows for efficient seeking.

The options are:

- **-A** \[*lzma* \| *zlib* \| *zstd*\]

  Select a specific compression algorithm. If this option is not provided, the default is *zlib*.

  The *lzma* algorithm provides noticeable better compression levels than zlib on the same data set. It has vastly slower compression speed and moderately slower decompression speed.

  The *zstd* algorithm provides better compression levels than zlib on the same data set. It also has faster compression and decompression speed than zlib. In the very high compression “level” settings, it does not offer quite as high a compression ratio as *lzma*. However, its decompression speed does not suffer at high compression “levels”.

- **-C** *compression\_level*

  Select the integer compression level used to parameterize the chosen compression algorithm.

  For any given algorithm, a lesser number selects a faster compression mode. A greater number selects a slower compression mode. Typically, for the same algorithm, a greater *compression\_level* provides better final compression ratio.

  For *lzma*, the range of valid compression levels is *0-9*. The **mkuzip** default for lzma is *6*.

  For *zlib*, the range of valid compression levels is *1-9*. The **mkuzip** default for zlib is *9*.

  For *zstd*, the range of valid compression levels is currently *1-19*. The **mkuzip** default for zstd is *9*.

- **-d**

  Enable de-duplication. When the option is enabled **mkuzip** detects identical blocks in the input and replaces each subsequent occurrence of such block with pointer to the very first one in the output. Setting this option results is moderate decrease of compressed image size, typically around 3-5% of a final size of the compressed image.

- **-j** *compression\_jobs*

  Specify the number of compression jobs that **mkuzip** runs in parallel to speed up compression. When option is not specified the number of jobs set to be equal to the value of *hw.ncpu* [sysctl(8)](/sysctl/8.md) variable.

- \[**-L**\]

  Legacy flag that indicates the same thing as “**-A** *lzma*”.

- **-o** *outfile*

  Name of the output file *outfile*. The default is to use the input name with the suffix *.uzip* for the [zlib(3)](/zlib/3.md) compression or *.ulzma* for the lzma(3).

- **-S**

  Print summary about the compression ratio as well as output file size after file has been processed.

- **-s** *cluster\_size*

  Split the image into clusters of *cluster\_size* bytes, 16384 bytes by default. The *cluster\_size* should be a multiple of 512 bytes.

- **-v**

  Display verbose messages.

- **-Z**

  Disable zero-block detection and elimination. When this option is set, **mkuzip** compresses blocks of zero bytes just as it would any other block. When the option is not set, **mkuzip** detects and compresses zero blocks in a space-efficient way. Setting **-Z** increases compressed image sizes slightly, typically less than 0.1%.

## IMPLEMENTATION NOTES

The compression ratio largely depends on the compression algorithm, level, and cluster size used. For large cluster sizes (16kB and higher), typical overall image compression ratios with [zlib(3)](/zlib/3.md) are only 1-2% less than those achieved with [gzip(1)](/gzip/1.md) over the entire image. However, it should be kept in mind that larger cluster sizes lead to higher overhead in the [geom\_uzip(4)](/geom_uzip/4.md) class, as the class has to decompress the whole cluster even if only a few bytes from that cluster have to be read.

Additionally, the threshold at 16-32 kB where a larger cluster size does not benefit overall compression ratio is an artifact of the [zlib(3)](/zlib/3.md) algorithm in particular. *Lzma* and *Zstd* *will* *continue* *to* *provide* *better* *compression* *ratios* *as* *cluster* *sizes* are increased, at high enough compression levels. The same tradeoff continues to apply: reads in [geom\_uzip(4)](/geom_uzip/4.md) become more expensive the greater the cluster size.

The de-duplication is a FreeBSD specific feature and while it does not require any changes to on-disk compressed image format, however it did require some matching changes to the [geom\_uzip(4)](/geom_uzip/4.md) to handle resulting images correctly.

To make use of *zstd* **mkuzip** images, the kernel must be configured with **ZSTDIO**. It is enabled by default in many **GENERIC** kernels provided as binary distributions by FreeBSD. The status on any particular system can be verified by checking [sysctl(8)](/sysctl/8.md) kern.features.geom\_uzip\_zstd for “1”.

## EXIT STATUS

The **mkuzip** utility exits 0 on success, and \>0 if an error occurs.

## EXAMPLES

The following describes how to create and mount a uzip image.

Create a file system image:

```
makefs /src.img /usr/src
```

Create the uzip image, the output file will be named src.img.uzip:

```
mkuzip /src.img
```

Ensure geom\_uzip is loaded:

```
kldload geom_uzip
```

Create an MD device backed by the uzip image:

```
mdconfig -f /src.img.uzip
```

Mount the uzip image:

```
mount -o ro /dev/md0.uzip /mnt
```

## SEE ALSO

[gzip(1)](/gzip/1.md), [xz(1)](/xz/1.md), [zstd(1)](/zstd/1.md), [zlib(3)](/zlib/3.md), [geom(4)](/geom/4.md), [geom\_uzip(4)](/geom_uzip/4.md), [md(4)](/md/4.md), [mdconfig(8)](/mdconfig/8.md), [mount\_cd9660(8)](/mount_cd9660/8.md)

## AUTHORS

Maxim Sobolev ⟨*sobomax@FreeBSD.org*⟩