zram-config moves swap, working directories and logs into compressed RAM

Why flash storage makes this worth automating

zram-config is described as a complete zram-config utility for swap, directories and logs to reduce SD, NAND and eMMC block wear, and the problem it addresses is specific to flash media. On an SD card, a Linux install writes constantly: logs, package caches, temporary files, journal output, and the small random writes that a spinning disk absorbs without noticing. Every one of those is a write cycle against a medium that has a finite write endurance, and on a Raspberry Pi the wear shows up as a slowing card and then a failing one. The tool's answer is to hold the volatile parts of the filesystem in RAM. zram allows near RAM speed access to working directories and prevents frequent writing to persistent storage, and because data stored in zram can be compressed, the amount of memory consumed by a given directory is smaller than the directory's nominal size. The design goal is not speed for its own sake. It is fewer writes to the flash, with the speed as a side effect, and the documentation puts it in those terms.

The /etc/ztab table and how OverlayFS avoids a startup copy

Configuration is a table, and the table is the whole interface. A file located at /etc/ztab is used to configure any number and type of zram devices, where you comment out any line with a hash, add new drives with the first column providing the drive type and then the drive details separated by tab characters. Three drive types appear in the example configuration, swap, dir and log, and each row carries an algorithm and size fields.

# swap	alg		mem_limit	disk_size	swap_priority	page-cluster	swappiness
swap	lzo-rle		250M		750M		75		0		150

# dir	alg		mem_limit	disk_size	target_dir
#dir	lzo-rle		50M		150M		/home/pi

# log	alg		mem_limit	disk_size	target_dir	oldlog_dir
log	lzo-rle		50M		150M		/var/log	/opt/zram/oldlog

The mechanism behind the directory and log rows is OverlayFS. Using the table, an OverlayFS mount is used to mount the newly created zram device as the upper filesystem, and OverlayFS is used so that files do not need to be copied from persistent storage to RAM on startup. In theory this should allow for faster boots and larger directories, since no complete directory copy is needed. A version of kmxz/overlayfs-tools is used to implement the OverlayFS sync logic, and that project is vendored into this repository as a submodule, which is why the tree has an overlayfs-tools directory. The result is that a directory declared in the table appears at the same path as before, with writes landing in RAM and the underlying persistent copy updated on sync.

Reading the numbers: mem_limit, disk_size, page-cluster and swappiness

Four fields carry the tuning and each has a documented rationale. The mem_limit is the compressed memory limit and sets a hard memory limit for the system administrator, and setting it to 0 disables it. The disk_size is the maximum size of the uncompressed memory, and it should be set to roughly 150% of mem_limit depending on the algorithm and how compressible the input files are, with the warning not to make it much higher than the compression algorithm and the additional zram overhead are capable of, because there is a memory overhead of about 0.1% when empty. The swap_priority sets zram over alternative swap devices. The page-cluster value of 0 means tuning to singular pages rather than the default of 3, which caches 8 for hard disk tuning and can lower latency. The swappiness is 150 because the improved performance of zram allows more usage without adverse effects from the default of 60, and it can be raised up to 200, which improves performance in high memory pressure situations. On the algorithm choice, all algorithms in /proc/crypto are supported, but only lzo-rle, lzo, lz4 and zstd have zramctl text strings, with lzo-rle the fastest and zstd having much better text compression.

Installing from a release archive

The install path assumes the gh command line tool is installed and set up on your system, and the sequence downloads a release archive rather than cloning the repository.

gh release download --repo ecdye/zram-config --pattern '*.tar.lz'
mkdir -p zram-config && tar -xf zram-config*.tar.lz --strip-components=1 --directory=zram-config
sudo ./zram-config/install.bash

The first command fetches the packaged archive, the second unpacks it into a directory called zram-config with the leading path component stripped, and the third runs the installer with root privileges. The project also ships install.bash, update.bash and uninstall.bash at the top level of the tree, so a clone of the repository works just as well as the release archive. The repository also carries an overlayfs-tools submodule directory and a service/ directory, which is where the systemd unit and the sync timer live, and the tests/ directory with a test workflow badge alongside a ShellCheck badge, so the shell code is linted in CI.

Starting, stopping and syncing: the point where data can be lost

The lifecycle commands are where the risk sits. On Debian you use sudo systemctl {start|stop} zram-config.service to start or stop zram-config, and on Alpine you use sudo rc-service zram-config {start|stop}. The documentation is explicit about why stopping matters, saying this will ensure that any changes are properly synced to the persistent storage before system poweroff. If you sync only one single target instead of all the targets specified in /etc/ztab, you can add an additional option to the sync parameter like sudo zram-config sync "/example/targetfolder". The default sync service, which syncs files to disk every night, is not installed by default and must be installed separately.

sudo /path/to/zram-config/install.bash sync

That last point is the one to internalise. The tool assumes the normal path is a clean stop, and if you are worried about losing data because of a sudden power loss you can use the sync command to ensure changes are synced to disk periodically. A nightly sync reduces the window but does not close it, and a device that loses power between the last sync and the failure keeps whatever was written since. Updating is a single script, sudo /path/to/zram-config/update.bash, and there is a custom variant, sudo /path/to/zram-config/update.bash custom, for when you have made changes to the code or want to check out a specific branch or tag and prevent it from updating or resetting all changes. Removal is sudo /usr/local/share/zram-config/uninstall.bash.

Multiple devices, and editing a table while the tool is running

If you need multiple zram swaps or zram directories, you create another entry in /etc/ztab, and the documentation gives the exact sequence for that. To add new entries you edit /etc/ztab, and if you need to edit an active zram device you must stop zram with sudo systemctl stop zram-config.service on Debian or sudo rc-service zram-config stop on Alpine and then edit the entries you need. Once finished, you start zram using sudo systemctl start zram-config.service or sudo rc-service zram-config start, which will only add the new entries if zram is already running. That last clause is worth pausing on, because it means a start command on a running system is additive rather than a reconfiguration, so the safe workflow for a changed table is stop, edit, start. The three device types map onto three different use cases. A swap row gives you a compressed swap device. A dir row names a target_dir, which is the directory you wish to hold in zram, and the original is moved to a bind mount and is synchronized on start, stop and write commands. A log row adds an oldlog_dir, which enables log rotation to an off device directory while retaining only live logs in zram, and that directory is usually in /opt or /var, with the name optional.

Confirming it works, and where the project stops being supported

The verification step is a single command, and the documentation gives the expected output so you can compare it.

pi@raspberrypi:~$ zramctl
NAME       ALGORITHM DISKSIZE  DATA  COMPR TOTAL STREAMS MOUNTPOINT
/dev/zram1 lzo-rle       150M 16.9M 373.2K  692K       4 /opt/zram/zram1
/dev/zram0 lzo-rle       750M    4K    87B   12K       4 [SWAP]

If you see output similar to that, it is working, and if the zramctl command is missing you need to install the util-linux package to have a convenient way to view the zram status. The df output is the companion check, where an overlay1 line mounted on /var/log and a /dev/zram1 line confirm the log and directory devices. On support, the tool is primarily developed and tested against Raspberry Pi OS, any Debian derivative should also work out of the box, however there is no guarantee, and experimental Alpine support has been added, with other distributions possibly working but again without a guarantee. The licence is MIT and the release history shows v1.7.0 in December 2024, v1.6.0 in July 2024 and v1.5.0 in March 2022, with the last push to the repository on 2026-06-24.

Where zram-config is the wrong tool

The limits are inherent to the approach and worth stating before you point it at a directory that matters. The first is memory. A directory held in zram consumes physical RAM, compressed, and the compression ratio depends entirely on the data, so a directory of already compressed or mostly random content will not shrink and will simply eat the memory you allocated, with the OOM killer as the failure mode. The second is durability, since everything in the ram-backed directories lives only until it is synced, and the default configuration has no sync timer at all, which means an unclean shutdown loses everything written since the last sync. The third is that this is a Linux tool for flash media and it does not try to be anything else, so it is not a swap manager for a workstation with plenty of RAM, and it is not a way to speed up a build on an SSD. The fourth is the platform support, which the documentation itself hedges, and the guarantee is explicitly limited to Raspberry Pi OS with Debian derivatives working out of the box and Alpine being experimental. A separate but related point is that zramctl is the tool for inspecting zram devices generally, and simpler swap-only setup paths exist that involve far less machinery than a table, an OverlayFS mount and a sync timer. If all you need is compressed swap, the built-in mechanisms are the shorter path; zram-config earns its complexity when you also want whole directories and live logs kept off the flash.

Editorial conclusion

Adopt zram-config if you run Linux on flash storage and can tolerate the trade of holding data in RAM, since the utility compresses working directories and logs and syncs them back on a schedule or on shutdown. Do not adopt it on a machine where the amount of data in the ram-backed directories can exceed physical memory, because the disk size and memory limit relationship in /etc/ztab is a promise about compressibility rather than a guarantee, and do not adopt it if you need crash consistency, since an unclean poweroff loses whatever has not been synced. Verify two things before you point it at a production directory: that your chosen compression algorithm is one of the four with usable zramctl text strings, lzo-rle, lzo, lz4 or zstd, and that you have a sync schedule in place, because the default sync service is not installed automatically. The practical first step is to install the tool with the documented release download and install script, then run zramctl to confirm the devices exist before you move any directory.

Frequently asked questions

Official sources

1. ecdye/zram-config on GitHub
2. Issues
3. License: MIT
4. README
5. Releases