zswap

zswap is a kernel feature that provides a compressed RAM cache for swap pages. Pages which would otherwise be swapped out to disk are instead compressed and stored into a memory pool in RAM. Once the pool is full or the RAM is exhausted, the least recently used (LRU) page is decompressed and written to disk, as if it had not been intercepted. After the page has been decompressed into the swap cache, the compressed version in the pool can be freed.

The difference compared to zram is that zswap works in conjunction with a swap device while zram with created swap on top of it is a swap device in RAM that does not require a backing swap device.

Toggling zswap

Tip: linux-lts, linux-rt and linux-rt-lts have zswap enabled by default. This can be verified with zgrep CONFIG_ZSWAP_DEFAULT_ON /proc/config.gz.

zswap can be toggled at runtime, by writing either 1 (to enable) or 0 (to disable) to /sys/module/zswap/parameters/enabled. For example, to disable it at runtime:

# echo 0 > /sys/module/zswap/parameters/enabled

To enable zswap permanently, add zswap.enabled=1 to your kernel parameters. To disable zswap permanently on kernels where it is enabled by default, add zswap.enabled=0 instead.

Customizing zswap

Current parameters

zswap has several customizable parameters. The live settings can be displayed using:

$ grep -r . /sys/module/zswap/parameters/

/sys/module/zswap/parameters/same_filled_pages_enabled:Y
/sys/module/zswap/parameters/enabled:Y
/sys/module/zswap/parameters/max_pool_percent:20
/sys/module/zswap/parameters/compressor:zstd
/sys/module/zswap/parameters/non_same_filled_pages_enabled:Y
/sys/module/zswap/parameters/zpool:zsmalloc
/sys/module/zswap/parameters/exclusive_loads:N
/sys/module/zswap/parameters/accept_threshold_percent:90

See the zswap documentation for the description of the different parameters.

For more information about exclusive_loads parameter (which is not currently in zswap documentation), see this commentary in linux kernel source code.

The boot time load message showing the initial configuration can be retrieved with:

# dmesg | grep zswap:

[    0.317569] zswap: loaded using pool zstd/zsmalloc

Set parameters

Using sysfs

Each setting can be changed at runtime via the sysfs interface. For example, to change the compressor parameter:

# echo lz4 > /sys/module/zswap/parameters/compressor

Using kernel boot parameters

To persist the parameter change, the corresponding option, for example zswap.compressor=lz4, must be added to the kernel boot parameter. Therefore to set permanently all the above settings, the following kernel parameters must be added:

zswap.enabled=1 zswap.compressor=lz4 zswap.max_pool_percent=20 zswap.zpool=zsmalloc

When changing the compression algorithm via boot parameter, one needs to ensure the corresponding compression module is loaded early during boot (refer to #Compression algorithm).

Maximum pool size

The memory pool is not preallocated, it is allowed to grow up to a certain limit in percentage of the total memory available, by default up to 20% of the total RAM. Once this threshold is reached, pages are evicted from the pool into the swap device. The maximum compressed pool size is controlled with the parameter max_pool_percent.

Compressed memory pool allocator

The zpool parameter controls the management of the compressed memory pool.

In kernels after 6.3 zsmalloc allocator was added. It is supposed to work well under low memory conditions and it saves more memory.

For older kernels, the zbud data allocator is available, which stores exactly two compressed pages into one, which limits the compression ratio to 2 or less.

Similarly, the z3fold allocator allows up to 3 compressed objects by page (with a typical compression ratio averaging around 2.7, compared with 1.7 for zbud). This allocator was previously suggested over zsmalloc because it had better performances, but as this is no longer true and because of numerous bugs, it has been deprecated and disabled by default since 6.13 (backported to 6.6 LTS in 6.6.55) and is scheduled for removal.

A zpool of type zsmalloc is created by default. Use the kernel parameter zswap.zpool to select another allocator at boot time. The data allocator can also be changed at a later stage via the sysfs interface.

Compression algorithm

For page compression, zswap uses compressor modules provided by the kernel's cryptographic API. In official kernels the zstd compression algorithm is used by default but this can be changed with zswap.compressor= at boot time. Other options include deflate, lzo, 842, lz4 and lz4hc.

There is no issue changing the compression at runtime using sysfs but zswap starts in this case with zstd and switches at a later stage to the defined algorithm. To start zswap with another algorithm straight away, this must be set via the kernel boot parameters and the corresponding module must be loaded early by the kernel. This can be achieved by following these steps:

Add the modules required for the chosen compressor to the mkinitcpio#MODULES array.
Regenerate the initramfs.
Set the compression algorithm using the zswap.compressor= kernel parameter.

On next boot, see #Current parameters to check if zswap now uses the requested compressor.

Disable writeback

zswap has a a per-cgroup option to disable writeback (i.e. to prevent writes to disk).

See Power management/Suspend and hibernate#Disable zswap writeback to use the swap space only for hibernation for an example use case.

Zswap statistics

To see zswap statistics you can run this:

# grep -r . /sys/kernel/debug/zswap

/sys/kernel/debug/zswap/same_filled_pages:26274
/sys/kernel/debug/zswap/stored_pages:159898
/sys/kernel/debug/zswap/pool_total_size:171565056
/sys/kernel/debug/zswap/written_back_pages:787323
/sys/kernel/debug/zswap/reject_compress_poor:0
/sys/kernel/debug/zswap/reject_compress_fail:15860
/sys/kernel/debug/zswap/reject_kmemcache_fail:0
/sys/kernel/debug/zswap/reject_alloc_fail:0
/sys/kernel/debug/zswap/reject_reclaim_fail:31
/sys/kernel/debug/zswap/pool_limit_hit:0