Skip to content

Raspberry Pi and Armbian ZRAM Setup, Benchmark, and Troubleshooting

Check the swap already running on your Pi before installing a ZRAM tool. Raspberry Pi OS Trixie can use rpi-swap to create compressed RAM swap with disk writeback. Start by identifying the swap device, what manages it, and whether it has a backing disk.

Quick answer: ZRAM on Raspberry Pi OS and Armbian

Run swapon --show and zramctl on the Pi. If dev-zram0.swap is managed by rpi-swap, use that package's configuration. On Armbian, check the image's built-in memory settings first.

Quick setup decision

Current state Action
rpi-swap owns the active swap Inspect the mechanism and backing storage. Use rpi-swap settings for any changes.
Armbian manages ZRAM Keep its memory configuration service and use the Armbian controls.
Custom Debian-based image without a manager for ZRAM Choose zram-tools or systemd-zram-generator if you need compressed swap.
Swap is active but has no owner you recognise Check systemd units and /etc/fstab before changing it.

Raspberry Pi OS or Armbian: identify the owner first

Run the inspection commands on the Pi in an ordinary terminal or over SSH. Include the system binary directories if your login's PATH omits tools such as swapon:

1
2
3
4
5
export PATH="$PATH:/usr/sbin:/sbin"
cat /etc/os-release
swapon --show=NAME,TYPE,SIZE,USED,PRIO
zramctl --output NAME,ALGORITHM,DISKSIZE,DATA,COMPR,TOTAL
systemctl show dev-zram0.swap -p Description -p ActiveState -p FragmentPath

If swapon is unavailable, cat /proc/swaps shows which swap devices are active. zramctl can list devices used for another purpose, so match its device name against the active swap list.

System Typical owner First configuration to inspect
Raspberry Pi OS with rpi-swap rpi-swap-generator and its generated swap unit /etc/rpi/swap.conf and /etc/rpi/swap.conf.d/
Custom image with zram-tools zramswap.service /etc/default/zramswap
Custom image with a standalone systemd generator configuration systemd-zram-setup@zram0.service /etc/systemd/zram-generator.conf and its drop-ins
Armbian armbian-zram-config.service /etc/default/armbian-zram-config

rpi-swap depends on systemd-zram-generator, so seeing both packages and a systemd-zram-setup service can be normal. Look at the generated unit's description and the package configuration before deciding who owns it. Armbian has its own setup route. Raspberry Pi rpi-swap documentation · Armbian configuration documentation

Read a real Raspberry Pi OS Trixie snapshot

On a Pi 4 Model B with rpi-swap 1.2.4 and kernel 6.18.50+rpt-rpi-v8, the commands reported:

1
2
3
4
5
6
7
8
9
NAME       TYPE      SIZE USED PRIO
/dev/zram0 partition   2G   0B  100

NAME       ALGORITHM DISKSIZE DATA COMPR TOTAL
/dev/zram0 zstd            2G   4K    0B    0B

Description=rpi-swap managed swap device (zram+file)
ActiveState=active
FragmentPath=/run/systemd/generator/dev-zram0.swap

2G was the logical swap capacity. It was using 0 bytes of swap at the moment of the check. zram+file tells you that an active ZRAM swap device can also move pages to backing storage. To see that backing device, run:

1
2
3
4
5
6
7
for field in backing_dev bd_stat; do
  path="/sys/block/zram0/$field"
  if [ -r "$path" ]; then
    printf '%s: ' "$field"
    cat "$path"
  fi
done

The Pi reported /dev/loop0 for backing_dev. Reading /sys/block/loop0/loop/backing_file then identified /var/swap. The file serves the ZRAM device through that loop device and does not appear as a second active swap entry. When present, bd_stat reports backing usage, reads, and writes in 4 KiB units. Compare two samples during your normal workload to see if writes increased. Linux ZRAM statistics

Configure rpi-swap through its own settings

For a Pi already managed by rpi-swap, read man 5 swap.conf for the options supported by that version. The package reads /etc/rpi/swap.conf and local overrides in /etc/rpi/swap.conf.d/. [Main] controls the Mechanism, such as zram or zram+file. [Zram] controls the size. FixedSizeMiB, when available, sets logical capacity in MiB. A larger value can lead to greater physical RAM use once pages move into swap.

Record the installed configuration and back up any override before changing it. Use one local drop-in for one change. Plan a clean reboot with a recovery route and inspect swapon, the unit and backing_dev again. The package applies its swap configuration during boot. Selecting a mechanism without a swap file can remove the package's existing backing file. rpi-swap configuration and reboot behaviour

ZRAM and zswap answer different questions

ZRAM is a block device that can appear in swapon --show as /dev/zram0. Zswap is a compressed cache in front of a swap device. It does not appear as its own swap device. On the Pi above, /sys/module/zswap/parameters/enabled read N, while ZRAM was active. A missing sysfs file only tells you that this check is unavailable on the running kernel. Linux zswap documentation

Inspect the current swap configuration

1
2
3
4
free -h
swapon --show=NAME,TYPE,SIZE,USED,PRIO
zramctl
lsmod | grep zram

Find installed packages and active units:

1
2
3
dpkg-query -W -f='${Package}\t${Status}\t${Version}\n' \
  rpi-swap zram-tools systemd-zram-generator 2>/dev/null
systemctl list-units --all | grep -Ei 'zram|swap'

If /dev/zram0 already exists, do not install another manager over it. Save its current configuration and measure the workload first.

Confirm that memory is the bottleneck

Reproduce the slow task while observing:

1
2
3
4
5
vmstat -y 1 5
if [ -r /proc/pressure/memory ]; then
  cat /proc/pressure/memory
fi
journalctl -k -b --no-pager | grep -Ei 'out of memory|oom-kill|killed process'
  • Continuous si and so in vmstat indicate swap traffic.
  • PSI some means at least one task is stalled on memory.
  • PSI full means all non-idle tasks are stalled together.
  • An OOM message identifies an allocation failure, but the root cause may be a leak or cgroup limit.

If /proc/pressure/memory is absent, use the swap samples, MemAvailable and application timing. Missing PSI is a missing measurement. Use the memory pressure and OOM diagnosis before choosing a size.

Method 1: zram-tools

Use this route on a custom Debian-based image only after confirming that neither rpi-swap nor another tool manages ZRAM:

sudo apt update
sudo apt install zram-tools

Edit its configuration:

sudo nano /etc/default/zramswap

Start conservatively:

1
2
3
ALGO=lz4
PERCENT=50
PRIORITY=100

PERCENT=50 sets the maximum ZRAM device capacity to half of physical RAM; it does not reserve half of RAM immediately. lz4 favors speed. Test zstd only as a separate experiment when compression ratio matters more than CPU cost and the installed kernel supports it.

Apply and verify:

1
2
3
4
sudo systemctl restart zramswap
systemctl status zramswap --no-pager
swapon --show=NAME,TYPE,SIZE,USED,PRIO
zramctl

If the service fails, inspect:

journalctl -b -u zramswap --no-pager

Method 2: systemd-zram-generator

Use this standalone configuration on a custom image where rpi-swap, zram-tools and Armbian's service do not manage the same ZRAM device:

1
2
3
sudo apt update
sudo apt install systemd-zram-generator
sudo nano /etc/systemd/zram-generator.conf

Example bounded configuration:

1
2
3
4
[zram0]
zram-size = min(ram / 2, 2048)
compression-algorithm = lz4
swap-priority = 100

The size expression is in MiB where a bare number is used. This example caps the device at 2 GiB. Confirm syntax against the installed manual because generator versions can differ:

man zram-generator.conf

Reboot to apply it cleanly:

sudo reboot

Then verify:

1
2
3
systemctl status systemd-zram-setup@zram0.service --no-pager
swapon --show=NAME,TYPE,SIZE,USED,PRIO
zramctl

Check for competing configurations

Check again after configuration:

dpkg -l rpi-swap zram-tools systemd-zram-generator 2>/dev/null
systemctl list-units --all | grep -Ei 'zram|swap'

Competing configuration can come from zramswap.service or a standalone generator configuration alongside rpi-swap. Identify which configuration creates each device and preserve required package dependencies. Check the proposed package changes if you are removing a tool.

Choose a starting size

Use a percentage as a test starting point, not a universal recommendation:

Workload Starting experiment What to watch
512 MiB interactive system 50% RAM CPU cost, PSI, browser/application latency
1–2 GiB service host 25–50% RAM OOM events, request p95, compression ratio
4–8 GiB system Enable only after pressure is observed Whether swap is used at all
Incompressible media or encrypted buffers Small test or no ZRAM Poor DATA to TOTAL efficiency

A ZRAM device can advertise more logical capacity than the physical memory it eventually consumes. If the workload fills it with poorly compressible pages, the system can still run out of RAM.

Read ZRAM statistics

zramctl --output NAME,ALGORITHM,DISKSIZE,DATA,COMPR,TOTAL,MOUNTPOINT
cat /sys/block/zram0/mm_stat

Important fields:

  • DISKSIZE: logical maximum capacity
  • DATA: uncompressed size of stored pages
  • COMPR: compressed payload size
  • TOTAL: physical memory consumed, including allocator overhead

Use TOTAL, not only COMPR, when judging memory cost. Compare the figures at the same point in the workload.

Swap priority and disk fallback

Display priorities:

swapon --show=NAME,TYPE,SIZE,USED,PRIO

Linux normally selects higher-priority swap first when it has separate active swap devices. With rpi-swap in zram+file mode, the backing file is internal to ZRAM. Changing swap priorities does not control when that device writes pages back.

Do not disable an existing swap file until you have console access and a controlled memory test. On a remote-only device, an OOM during reconfiguration can end the session.

Test compression algorithms

Show algorithms supported by the running kernel:

cat /sys/block/zram0/comp_algorithm

The active algorithm appears in brackets. Common trade-offs are:

Algorithm General tendency Test when
lz4 Lower CPU cost, fast compression/decompression Interactive latency matters
zstd Often higher compression, more CPU work Working set compresses well and CPU headroom exists

Do not switch an active device's algorithm while it holds swap. Change the manager configuration and reboot or recreate the device through that manager's documented procedure.

Treat vm.swappiness as a separate experiment

Inspect the current value:

sysctl vm.swappiness

Do not automatically set it to 10, 20, or 100. Its effect depends on workload and kernel behaviour. Keep the current value for the first ZRAM comparison. If testing it later, change only that variable, record it, and compare application latency, PSI, swap traffic, and OOM events.

Repeatable benchmark

Run at least five repetitions of the same task in each configuration:

Metric Baseline ZRAM
Workload completion time, seconds
p95 application latency, ms
Peak MemAvailable, MiB
Peak PSI some / full, %
Swap-in / swap-out, KiB/s
ZRAM DATA / COMPR / TOTAL, MiB n/a
OOM kills
Maximum temperature, °C

Keep board, OS, workload, cooling, storage, services, and starting temperature constant. Publish raw data rather than a single best run. See the benchmark methodology.

Remove ZRAM safely

For rpi-swap, change its mechanism through its documented settings and plan a clean reboot. The commands below are for the alternative setups described above. Before stopping swap, reduce memory pressure and make sure you can recover locally. For zram-tools:

1
2
3
4
free -h
sudo systemctl stop zramswap
swapon --show
sudo apt remove zram-tools

For the generator, first confirm no critical pages depend on its swap, then:

1
2
3
4
free -h
sudo swapoff /dev/zram0
sudo apt remove systemd-zram-generator
sudo reboot

swapoff can fail or trigger OOM when RAM is insufficient. Stop memory-heavy applications first and do not force it on a remote production system.

Troubleshooting

/dev/zram0 does not appear

1
2
3
systemctl status zramswap systemd-zram-setup@zram0.service --no-pager
journalctl -b | grep -i zram
modinfo zram

Confirm the configuration belongs to the manager you intend to use and matches the installed version. If you use rpi-swap, inspect the generated unit and man 5 swap.conf first.

Device or resource busy

Another service may already own the device. Inspect units, mounts, swap, and packages instead of resetting it manually:

1
2
3
zramctl
swapon --show
systemctl list-units --all | grep -i zram

Performance became worse

Check CPU saturation, temperature, throttling, compression efficiency, and PSI. Reduce the device size or return to the baseline if compression overhead exceeds the avoided storage latency.

OOM still occurs

ZRAM cannot fix an unbounded leak or a workload whose active set exceeds available memory. Inspect the killed process, systemd cgroup limits, and application concurrency with the OOM guide.

FAQ

Is ZRAM enabled by default on Raspberry Pi OS Trixie?

Many Trixie installations use rpi-swap, whose current automatic mode can choose zram+file. Existing overrides, older and custom images can differ. Check swapon --show, the running unit, and the backing device on the Pi itself.

Does ZRAM wear out RAM?

No. RAM does not have flash write endurance. ZRAM does consume memory bandwidth and CPU time.

Does ZRAM replace physical RAM?

No. It stores compressible inactive pages more densely. Active and incompressible working sets still require physical memory.

Which algorithm is best?

Start with lz4 for a latency-oriented baseline, then compare another supported algorithm using the same workload. The best choice depends on compressibility and CPU headroom.

Donate