---
name: "geom_uzip"
section: "4"
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/geom_uzip"
---

# geom\_uzip(4)

GEOM based compressed disk images and partitions

## NAME

**geom\_uzip** – GEOM based compressed disk images and partitions

## SYNOPSIS

To compile this driver into the kernel, place the following line in your kernel configuration file:

**device xz** **options zstd** **options GEOM\_UZIP**

Alternatively, to load the driver as a module at boot time, place the following line in [loader.conf(5)](/loader.conf/5.md):

```
geom_uzip_load="YES"
```

## DESCRIPTION

The **geom\_uzip** framework provides support for compressed read-only disk images. This allows significant storage savings at the expense of some CPU time on each read. Data written in the GEOM label area allows **geom\_uzip** to detect compressed images which have been created with [mkuzip(8)](/mkuzip/8.md) and presented to the kernel as a logical disk device via [md(4)](/md/4.md). **geom\_uzip** creates a unique *md#.uzip* device for each image.

**geom\_uzip** is not limited to supporting only [md(4)](/md/4.md) images. The image can also reside on a block device. (For example, a disk, USB flash drive, DVD-ROM, etc). The appropriate device node will appear with the *.uzip* suffix.

```
# gpart show da0
=>      0  7833600  da0  BSD  (3.7G)
        0  2097152    1  freebsd-ufs  (1.0G)
  2097152  5736448       - free -  (2.7G)
# gpart add -t freebsd-ufs -s 1G da0
da0b added
# dd if=/tmp/20160217_dcomp_zcomp.uzip bs=256k of=/dev/da0b
3190+1 records in
3190+1 records out
836331008 bytes transferred in 111.021489 secs (7533055 bytes/sec)
# fsck -t ffs /dev/da0b.uzip
** /dev/da0b.uzip (NO WRITE)
** Last Mounted on /mnt
** Phase 1 - Check Blocks and Sizes
** Phase 2 - Check Pathnames
** Phase 3 - Check Connectivity
** Phase 4 - Check Reference Counts
** Phase 5 - Check Cyl groups
97455 files, 604242 used, 184741 free (2349 frags, 22799 blocks,
   0.3% fragmentation)
# mount -o ro /dev/da0b.uzip /mnt
# df /dev/da0b.uzip
Filesystem     1K-blocks    Used  Avail Capacity  Mounted on
/dev/da0b.uzip   3155932 2416968 738964    77%    /mnt
```

The **geom\_uzip** device is subsequently used by FreeBSD kernel to access the uncompressed data. The **geom\_uzip** driver does not allow write operations to the underlying disk image. To check which “providers” match a given **geom\_uzip** device:

```
# geom uzip list
Geom name: md1.uzip
Providers:
1. Name: md1.uzip
   Mediasize: 22003712 (21M)
   Sectorsize: 512
Consumers:
1. Name: md1
   Mediasize: 9563648 (9.1M)
   Sectorsize: 512
Geom name: da0b.uzip
Providers:
1. Name: da0b.uzip
   Mediasize: 3355443200 (3.1G)
   Sectorsize: 512
Consumers:
1. Name: da0b
   Mediasize: 1073741824 (1.0G)
   Sectorsize: 512
```

**geom\_uzip** allows mounting the root file system from a compressed disk partition by setting the vfs.root.mountfrom tunable. See [loader.conf(5)](/loader.conf/5.md) for details.

## DIAGNOSTICS

Several flags are provided for tracing **geom\_uzip** I/O operations and TOC parsing via the following sysctls.

- *kern.geom.uzip.debug*

  Log level. Zero disables logging. Higher values enable more verbose debug logging for **geom\_uzip**. Supported levels are from 0 (no logging) to 4 (maximum amount of logging).

- *kern.geom.uzip.debug\_block*

  Log operations involving compressed cluster number.

## SEE ALSO

[GEOM(4)](/GEOM/4.md), [md(4)](/md/4.md), [geom(8)](/geom/8.md), [mkuzip(8)](/mkuzip/8.md)

## HISTORY

Zstd support was added in FreeBSD 13.0.

## AUTHORS

The **geom\_uzip** driver was written by Max Khon ⟨*fjoe@FreeBSD.org*⟩. The block de-duplication code as well as some **geom\_uzip** driver optimizations have been contributed by Maxim Sobolev ⟨*sobomax@FreeBSD.org*⟩. The LZMA decompression support and CLOOP 3.0 support have been added by Aleksandr Rybalko ⟨*ray@FreeBSD.org*⟩.

This manual page was written by Ceri Davies ⟨*ceri@FreeBSD.org*⟩.