Swap

Swap provides additional virtual memory by extending physical RAM. This can be accomplished by using space on disk, such as swap file or swap partition, or through compression based methods like zram. Additionally, zswap can act as a RAM-based compressed cache sitting in front of a traditional disk-based swap device.

Configuration

The following sections describe how to configure and manage swap on NixOS.

To check your current swap setup and usage, you can use the following command: swapon --show

Note: nixos-generate-config does not automatically generate a swapDevices entry if your system uses a swap file or /dev/zram for swap. For details, see the discussion on GitHub

Note: It's generally recommended to use either zram or zswap, but not both simultaneously, as they serve overlapping roles and may lead to suboptimal memory management behavior.

Swap file

A swap file provides swap space using a regular file on your filesystem, offering greater flexibility compared to a dedicated swap partition.

To add a swap file in NixOS, add the following:

❄︎ /etc/nixos/configuration.nix

swapDevices = [{
  device = "/var/lib/swapfile";
  size = 16*1024; # 16 GB
}];

The size value is specified in megabytes

Swap partition

Swap partitions are typically created during the initial disk partitioning phase of a NixOS installation. For instructions on creating swap partitions, see the relevant NixOS manual sections for UEFI/MBR partition schemes and formatting.

Zram swap

Zram is a kernel module for creating a compressed block device in RAM.

❄︎ /etc/nixos/configuration.nix

zramSwap.enable = true; # Creates a zram block device and uses it as a swap device

It is an alternative or complementary approach to swap disks, suitable for systems with enough RAM. In the event the system needs to swap it will move uncompressed RAM contents into the compressed area, saving RAM space while effectively increasing the available RAM at the cost of computational power for compression and decompression.

See zramSwap for a full list of available options and their descriptions.

Zram writeback

Zram supports writeback functionality, allowing idle or incompressible pages to be moved to a backing storage device rather than keeping it in memory. Currently, writeback can only use block storage devices (such as partitions) and does not support swap files. The backing partition must be manually created first, but does not require formatting.

An example configuration:

❄︎ /etc/nixos/configuration.nix

zramSwap = {
  enable = true; 
  writebackDevice = "/dev/sda1"

To verify the block storage device is being used:

cat /sys/block/zram0/backing_dev

Zswap swap cache

Zswap is a compress RAM cache for swap pages. It acts as a middle layer between system memory and a traditional disk-based swap device, storing compressed pages in RAM before optionally writing them out to disk-based swap if necessary.

Unlike zram, zswap requires a disk-based swap device to back it.

Zswap is controlled by kernel parameters and can be enabled in your NixOS configuration by setting appropriate options through boot.kernelParams.

❄︎ /etc/nixos/configuration.nix

  boot.kernelParams = [
    "zswap.enabled=1" # enables zswap
    "zswap.compressor=lz4" # compression algorithm
    "zswap.max_pool_percent=20" # maximum percentage of RAM that zswap is allowed to use
  ];

You can verify zswap's runtime status via cat /sys/module/zswap/parameters/enabled and inspect usage statistics with # grep -r . /sys/kernel/debug/zswap/

Disable swap

To remove all swap devices from NixOS, set the following to remove the swap partition or file from being included in /etc/fstab.

swapDevices = lib.mkForce [ ];

If you are using GPT partitioning tables, systemd-gpt-auto-generator(8) will still mount your swap partition automatically. You must therefore turn on attribute 63 on your partition in the partition table. This can be done with gptfdisk or similar:

gdisk /dev/sda
x
a
<partition number>
63
<enter>
w

Tips and Tricks

Encrypt swap with random key

Swap can be automatically encrypted with a new key on every boot. This can be used to simplify certain disk layouts, such as securing a swap file on a filesystem partition without an encryption container (such as LUKS).

swapDevices = [{
  device = "/dev/sdXY";
  randomEncryption.enable = true; 
}];

Adjusting swap usage behaviour

Swappiness controls how aggressibely swap space is used. By default, Linux uses a swappiness value of 60. Higher values will make the kernel prefer swapping out idle processes sooner. Conversely lower values will try to avoid swapping as much as possible, keeping processes in RAM unless absolutely necessary. An optimal value is workload dependent and will will require experimentation.

❄︎ /etc/nixos/configuration.nix

boot.kernel.sysctl = {
  "vm.swappiness" = 10;
};

You can see your current swappiness level by cat /proc/sys/vm/swappiness.

ZFS and swap

OpenZFS does not support swap on zvols nor do they support swap files on a ZFS dataset.

Instead you should set up a swap partition or swap file on a non-ZFS filesystem.

Using swap files on Btrfs

For Btrfs file system-specific considerations, see the Btrfs swap file section.

Swapspace

Swapspace is a dynamic swap space manager for GNU/Linux. i.e. it allows unused disk space to be utilised as swap to handle the occasional memory-intensive task, and frees the disk space once done.

Enable it via services.swapspace.enable = true; in your nixos configuration. And after switching, check that systemctl status swapspace.service is green, that's all, swapspace will auto manage swap for you.

See all the options it supports here, search.nixos.org

You can also use zramSwap along with this service.

See your active swap partitions/files with swapon. For eg.

⚠︎

Warning: Do not run the following without swapspace active + more than 34GB free disk space (assuming 8GB ram) OR without 42GB+ ram to spare.

# Read the WARNING above, and adjust 2, 20GB according to your free space
$ # nix shell nixpkgs#stress.out -c stress --vm 2 --vm-bytes 20G
$ swapon
NAME                 TYPE       SIZE  USED PRIO
/dev/zram0           partition 13.8G  2.6G    5
/var/lib/swapspace/1 file       5.2G 59.2M   -2
/var/lib/swapspace/2 file       6.1G 56.4M   -3