How it works
The zram kernel module creates a block device, /dev/zram0, that lives in memory. Everything written to it is
compressed. zram-tools turns that device into swap: at boot the zramswap.service unit runs the
/usr/sbin/zramswap script, which does five steps:
modprobe zram
ALGO > /sys/block/zram0/comp_algorithm
size > /sys/block/zram0/disksize bytes: SIZE × 1024 × 1024 or MemTotal × PERCENT / 100
mkswap /dev/zram0
swapon -p PRIORITY /dev/zram0
When memory runs low, the kernel moves rarely used pages to swap, just as with a file on disk. Only here the
“disk” is that same memory, and a page takes 2–3 times less space there. On a 2 GB server with Docker, nginx and redis under load,
TOTAL versus DATA in zramctl is 2.5–3.8 to 1 with zstd and 2–2.4 to 1 with lz4. No disk I/O is involved; a page goes out and comes
back at the cost of CPU.
The size in the config is how much uncompressed data fits in the device, not how much memory it takes. On a 1 GB
server with PERCENT=50 the device is 512 MB. Filled completely at 3 to 1 compression, it takes about 170 MB of
memory and frees 512.
What you get after installing
The package defaults differ between the two LTS releases: they changed in 0.3.4.
| Ubuntu 24.04 | Ubuntu 26.04 | |
|---|---|---|
zram-tools version |
0.3.3.1 | 0.3.7 |
/etc/default/zramswap |
every line commented out | ALGO, PERCENT, SIZE, PRIORITY set |
| size | 256 MB — the script’s default | 50% of memory |
| algorithm | lz4 |
lz4 |
| priority | 100 | 100 |
On 24.04, right after apt install, swap is 256 MB regardless of memory. That’s small for a 2 GB server, so edit
the config right away.
The config
ALGO=zstdzstd compresses tighter, lz4 is faster. On a small VPS memory is scarce, not CPU, so pick zstd: more pages fit in the same 50%. The algorithms your kernel has: cat /sys/block/zram0/comp_algorithm, the selected one in square brackets.
default lz4
PERCENT=50The device size as a percentage of MemTotal in /proc/meminfo. If this line is set, SIZE isn’t read. 50% on a 1–2 GB server: even completely full at 3 to 1, the device takes about a sixth of memory.
default 50 (26.04) · none (24.04)
SIZE=512The size in MiB, when no percentage is set. Use it if you want a fixed size regardless of memory: one image for servers with different memory.
default 512 (26.04) · 256 (24.04)
PRIORITY=100Swap priority. The kernel fills the higher-priority device first. A swap file enabled through /etc/fstab without pri= gets a negative priority (-2), so zram always goes first and the disk file only when zram is full.
default 100
The other lines in the file are comments. The syntax is shell: the script loads the file with source, so no
spaces around =.
Install it
Check that the module exists
sudo modprobe zram && ls /sys/block/ | grep zram # zram0Empty, or
modprobe: FATAL: Module zram not found— see “If it doesn’t work”. A module loaded for the check does no harm: the package’s script loads it the same way.Install the package
sudo apt install zram-toolsThe package is in
universewith one dependency,bc. Thezramswap.serviceunit enables and starts itself with the defaults from the table above.Edit the config
sudo tee /etc/default/zramswap >/dev/null <<'EOF' ALGO=zstd PERCENT=50 PRIORITY=100 EOFThe file is short, so write it whole. It’s a package conffile: if a new
zram-toolsversion changes it too,dpkgasks whose to keep — keep yours.Apply it
sudo systemctl restart zramswapRight after installation zram is empty, and the restart goes through without trouble. If swap is already full, see “If it doesn’t work”.
Kernel settings for zram
vm.swappiness tells the kernel which is cheaper: moving process pages to swap or dropping the file cache.
Swap, journal and time sets 10 for a disk file because disk swap is slow. zram is faster than any disk, so the value
goes higher. Kernels since 5.8 accept up to 200; 100 means swap and cache are equal.
sudo tee /etc/sysctl.d/99-zram.conf >/dev/null <<'EOF'
vm.swappiness=100
vm.page-cluster=0
EOF
sudo sysctl --system | grep -E 'swappiness|page-cluster'
# vm.swappiness = 100
# vm.page-cluster = 0
vm.page-cluster=0 turns off swap readahead. The default is 3: the kernel reads 8 consecutive pages from disk at
once, because for a disk that’s cheaper than 8 separate reads. zram decompresses each page separately, so the extra
7 are wasted work. The kernel documentation (sysctl/vm) doesn’t mention zram but explains the mechanism: the
lower the value, the faster the first access to a swapped page, and 0 disables readahead entirely.
If a disk swap file from Swap, journal and time stays alongside, delete 99-swappiness.conf with its 10: sysctl
reads files alphabetically, and the last value wins.
Other ways to swap in memory
| With | How it works | When to use |
|---|---|---|
zram-tools |
a script and a unit, a four-line config | Debian and Ubuntu, zram with nothing extra |
systemd-zram-generator |
a systemd generator creates zram at boot; config in /etc/systemd/zram-generator.conf |
Fedora does it this way; Ubuntu 26.04 has the package but defines no devices by default |
zram-config |
an old Ubuntu package: zram at half of memory, the kernel’s default algorithm (lzo-rle) |
already installed — replace it with zram-tools |
| zswap | a compressed in-memory cache in front of disk swap, built into the kernel | you have a swap file and a decent disk: fresh pages go to zswap, old ones to disk |
| a swap file | pages go to disk | almost always, with zram or instead of it (Swap, journal and time) |
Don’t enable zram and zswap together: a page gets compressed twice. Check whether zswap is on with
cat /sys/module/zswap/parameters/enabled; N means off. That’s the default on Ubuntu 24.04 and 26.04 kernels: CONFIG_ZSWAP_DEFAULT_ON isn’t set.
If it doesn’t work
zramswap.service failed; the journal says Error: inserting the zram kernel module
- Cause
- The kernel has no
zrammodule. A VPS on container virtualization (LXC, OpenVZ) has no kernel of its own at all; Ubuntu kernels shipzram.koinlinux-modules-extra, which cloud images often lack. - Fix
sudo modprobe zramshows the reason. With your own kernel, installlinux-modules-extra-$(uname -r): on Ubuntu 24.04 the module is there, not in the baselinux-modules; on 26.04 it’s already in the base package. On a container VPS there’s no zram — use a swap file (Swap, journal and time).
Changed ALGO or PERCENT, but zramctl shows the old values
- Cause
- Size and algorithm can only be set while the device is empty.
systemctl restart zramswapfirst runsswapoff, which fails if there’s nowhere to put the pages from zram back: memory is short. - Fix
- A reboot is the shortest way. Without one — at a quiet time, when
DATAinzramctlis small:sudo systemctl restart zramswap.
zramswap.service won’t start; the log shows echo: write error: Device or resource busy and Error: setting compression algo to zstd
- Cause
/dev/zram0is already taken:systemd-zram-generatoror the oldzram-configis installed too and created the device first. A configured device won’t change its algorithm, so the script fails on its first write to/sys/block/zram0.- Fix
- Keep one package.
apt list --installed 2>/dev/null | grep zramshows what’s installed; remove the extra one withsudo apt purgeand reboot.
There’s swap, but processes still get killed by Out of memory
- Cause
- zram borrows from the same memory. Data that doesn’t compress (archives, images, already compressed pages) takes almost as much space in zram as without it, so nothing is gained.
- Fix
- Compare
DATAandCOMPRinzramctl: compression worse than 1.5 to 1 means zram won’t save you. Add a low-priority swap file on disk (Swap, journal and time) or more memory.
The server got sluggish; top shows high sy and kswapd0
- Cause
- Memory is short all the time, and the CPU is busy compressing and decompressing pages back and forth.
- Fix
- Swap gets you through spikes; it doesn’t cure a constant shortage. Find who eats the memory (
ps aux --sort=-rss | head), limit the containers, or add memory.
How to check
zramctl
# NAME ALGORITHM DISKSIZE DATA COMPR TOTAL STREAMS MOUNTPOINT
# /dev/zram0 zstd 983.8M 4K 59B 20K 2 [SWAP]
swapon --show
# NAME TYPE SIZE USED PRIO
# /dev/zram0 partition 983.8M 0B 100
# /swapfile file 2G 0B -2
systemctl is-enabled zramswap
# enabled
DISKSIZE is half of memory (MemTotal on a 2 GB server is about 1968 MiB), ALGORITHM is zstd, and zram’s priority 100 is above the file’s.
Under load, check zramctl again: DATA is how much was swapped out, TOTAL is what it costs in memory. After a
reboot, the same.