SWAPON(8)

✨ SWAPON(8) ✨

okay bestie, we're in the System Administration chapter of the manual, and today's main characters are swapon and swapoff 💅

---

🌸 NAME 🌸

swapon, swapoff — turn devices and files on/off for paging and swapping 🦋

---

🎀 SYNOPSIS 🎀

swapon [options] [specialfile...]

swapoff [-va] [specialfile...]

---

💖 DESCRIPTION 💖

swapon is the vibe-setter: you use it to name the devices where paging and swapping are gonna happen. periodt.

The device or file you're working with is the specialfile parameter. It can also show up as -L label or -U uuid to point at a device by its label or its uuid. iykyk 💫

Calls to swapon normally happen inside your system boot scripts, making every swap device available — that way the paging and swapping activity gets interleaved across several devices and files. main character energy fr fr 🔥

swapoff does the opposite, obviously: it disables swapping on the devices and files you name. And when you pass the -a flag, swapping gets disabled on all known swap devices and files (as found in /proc/swaps or /etc/fstab). no cap 💀

---

🫶 OPTIONS 🫶

• -a, --all — every device marked as "swap" in /etc/fstab gets made available, except the ones with the "noauto" option. Devices that are already being used as swap are silently skipped (no drama, they just get skipped). Peep the FSTAB CONFIGURATION section below for the deets 💜
• -T, --fstab path — points at an alternative fstab file, for compatibility with mount(8). If path is a directory, the files inside get sorted by strverscmp(3); files that start with "." or that don't have an .fstab extension are ignored. You can specify this option more than once. It's mostly designed for initramfs or chroot scripts, where you've got extra configuration beyond the standard system config 🌈
• -d, --discard[=policy] — enables swap discards, but only if the swap backing device actually supports the discard or trim operation. This may improve performance on some Solid State Devices, but ngl, often it does not 🙈 The option lets you pick between two available swap discard policies:
  • --discard=once — performs a single-time discard operation for the whole swap area at swapon; or
  • --discard=pages — asynchronously discards freed swap pages before they become available for reuse.

If you don't select a policy, the default behavior is to enable both discard types. The /etc/fstab mount options discard, discard=once, or discard=pages may also be used to enable discard flags ✨

• -e, --ifexists — silently skips devices that don't exist. The /etc/fstab mount option nofail may also be used to skip a non-existing device 🍓
• -f, --fixpgsz — reinitializes (execs mkswap) the swap space if its page size doesn't match that of the current running kernel. Heads up: mkswap(8) initializes the whole device and does not check for bad blocks. you've been warned 😭
• -L label — use the partition that has the specified label. (For this, access to /proc/partitions is needed.) 👑
• -o, --options opts — specify swap options with an fstab-compatible comma-separated string. Like, for example:

swapon -o pri=1,discard=pages,nofail /dev/sda2

The opts string is evaluated last and overrides all other command line options. it's giving final boss 🧚

• -p, --priority priority — specify the priority of the swap device. priority is a value between 0 and 32767. Higher numbers indicate higher priority. See swapon(2) for a full description of swap priorities. Add pri=value to the option field of /etc/fstab for use with swapon -a. When no priority is defined, the Linux kernel defaults to negative numbers 💫
• -s, --summary — display swap usage summary by device. Equivalent to cat /proc/swaps. ⚠️ This output format is DEPRECATED in favour of --show, which gives you better control over the output data.
• --show[=column...] — display a definable table of swap areas. See the --help output for a list of available columns 🔥
• --output-all — output all available columns. all of them. every single one 💅
• --annotate[=when] — adds an annotation to each column header name. Terminals that support this feature can show that annotation as a tooltip. The optional when argument can be always, never, or auto. If the argument is omitted, it defaults to auto, which means annotations only get used when the output goes to a terminal ✨
• --noheadings — do not print headings when displaying --show output 🙈
• --raw — display --show output without aligning table columns 😌
• --bytes — display swap size in bytes in --show output instead of in user-friendly units 🌸
• -U uuid — use the partition that has the specified uuid. 🦋
• -v, --verbose — be verbose. spill the tea ☕
• -h, --help — display help text and exit 🫶
• -V, --version — display version and exit ⭐

---

💜 FSTAB CONFIGURATION 💜

The command swapon --all reads configuration from /etc/fstab (or from a file specified by the --fstab command line option). Only fstab entries with the filesystem type (3rd field) set to "swap" are relevant. everything else? irrelevant, bye 👋

The option --options accepts values in the same form as can be specified in the fourth field in fstab.

🌈 The first field (source)

Specify the swap source. If the source is a regular file, it's addressed by an absolute path.

If the swap is a block device, it can be addressed by device path, swap area tags LABEL= or UUID= (see mkswap(8) for more details), or by partition tags like PARTLABEL= or PARTUUID=. so many ways to identify a device, iconic honestly 👑

🎀 The second field (target)

Unused by swapon. The recommended convention is to use "none". it's just there for the vibes 🍓

✨ The third field (type)

Requires "swap" as the filesystem type. non-negotiable 💅

🦋 The fourth field (options)

It's formatted as a comma-separated list of options. All unknown options are silently ignored. If options are unnecessary, the recommended convention is to use "defaults". The options specified in fstab extend or overwrite settings specified on the swapon command line. 😮💨

Supported swap options:

• noauto — ignore this entry when swapon --all is given.
• nofail — do not report errors for this device if it does not exist.
• discard[=policy] — enable swap discard. The supported settings are discard, discard=once, or discard=pages. For more details, see the --discard command line option.
• pri=priority — specify the priority of the swap device. For more details, see the --priority command line option.

💫 The fifth field

Unused by swapon. The recommended convention is to keep it empty. 🫶

🌸 The sixth field

Unused by swapon. The recommended convention is to keep it empty. 💖

---

🔥 EXIT STATUS 🔥

swapoff has the following exit status values since v2.36:

1. 0 — success ✨
2. 2 — system has insufficient memory to stop swapping (OOM) 😭
3. 4 — swapoff(2) syscall failed for another reason
4. 8 — non-swapoff(2) syscall system error (out of memory, ...)
5. 16 — usage or syntax error 💀
6. 32 — all swapoff failed on --all
7. 64 — some swapoff succeeded on --all

The command swapoff --all returns 0 (all succeeded), 32 (all failed), or 64 (some failed, some succeeded).

• The old versions before v2.36 have no documented exit status. 0 means success in all versions. 🕰️

---

⭐ ENVIRONMENT ⭐

• LIBMOUNT_DEBUG=all — enables libmount debug output.
• LIBBLKID_DEBUG=all — enables libblkid debug output.

---

🍓 FILES 🍓

• /dev/sd?? — standard paging devices
• /etc/fstab — ascii filesystem description table

---

💀 NOTES 💀

🧚 Files with holes

The swap file implementation in the kernel expects to be able to write to the file directly, without the assistance of the filesystem. This is a problem on files with holes, or on copy-on-write files on filesystems like Btrfs. 😬

Commands like cp(1) or truncate(1) create files with holes. These files will be rejected by swapon.

Preallocated files created by fallocate(1) may be interpreted as files with holes too, depending on the filesystem. Preallocated swap files are supported on XFS since Linux 4.18. 🎉

The most portable solution to create a swap file is to use dd(1) and /dev/zero. that's the safe route bestie, trust 🫶

🌈 Btrfs

Swap files on Btrfs are supported since Linux 5.0, on files with the nocow attribute. See the btrfs(5) manual page for more details.

Since version 2.41, the command mkswap --file can create a new swap file with the nocow attribute. ✨

😭 NFS

Swap over NFS may not work. that's it, that's the note 💀

👑 Suspend

swapon automatically detects and rewrites a swap space signature with old software suspend data (e.g., S1SUSPEND, S2SUSPEND, ...). The problem is that if we don't do it, then we get data corruption the next time an attempt at unsuspending is made. so like, thank u swapon 🙏

---

🕰️ HISTORY 🕰️

The swapon command appeared in 4.0BSD. an absolute legend fr fr 💅

---

🌟 SEE ALSO 🌟

swapoff(2), swapon(2), fstab(5), init(8), fallocate(1), mkswap(8), mount(8), rc(8)

---

🙈 REPORTING BUGS 🙈

For bug reports, use the issue tracker <https://github.com/util-linux/util-linux/issues>. please actually report them, we wanna know 🫶

---

🎀 AVAILABILITY 🎀

The swapon command is part of the util-linux package which can be downloaded from Linux Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>. 🦋

---

and that's the whole page bestie!! this one came from util-linux 2.42.4, dated 2026-09-21 — so if ur reading this way later, maybe go vibe check for a newer one 💖✨