SWAPON(8)

💖 SWAPON(8) — the swap girlies' manual (System Administration) 💖

okay bestie, welcome to swapon and swapoff, two icons from the util-linux world, section 8, system administration division. they're literally the reason your RAM gets to breathe. let's get into it 🫶

---

✨ NAME ✨

swapon, swapoff — enable/disable devices and files for paging and swapping

---

🌸 SYNOPSIS 🌸

swapon [options] [specialfile...]

swapoff [-va] [specialfile...]

---

🦋 DESCRIPTION 🦋

so swapon is the one you call to specify which devices are gonna host your paging and swapping. it's giving "here's where the overflow goes, babe" 💅

the device or file you're blessing is given by the specialfile parameter. and get this — it can also be in the form -L label or -U uuid, which is how you point at a device by its label or its uuid. iconic, flexible, no notes.

calls to swapon normally happen inside the system boot scripts, where all your swap devices get made available — so that paging and swapping activity gets interleaved across several devices and files. multitasking queen behavior fr fr ✨

swapoff is the opposite vibe: it disables swapping on the devices and files you name. and when you hand it the -a flag, swapping gets disabled on all known swap devices and files (as found in /proc/swaps or /etc/fstab). bye bye swap 👋

---

💅 OPTIONS 💅

• -a, --all — every device marked as "swap" in /etc/fstab gets made available, EXCEPT the ones with the "noauto" option. devices already being used as swap are silently skipped (no drama, no errors). peep the FSTAB CONFIGURATION section below for the tea.
• -T, --fstab path — specifies an alternative fstab file, for compatibility with mount(8). if path is a directory, the files inside get sorted by strverscmp(3); files starting with "." or without an .fstab extension get ignored. you can pass this option more than once. it's mostly designed for initramfs or chroot scripts, where extra config lives beyond the standard system config. very niche, very valid.
• -d, --discard[=policy] — enables swap discards, IF the swap backing device supports the discard or trim operation. this may improve performance on some Solid State Devices, but often it does not (ngl, temper your expectations). 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're available for reuse.
  • if no policy is selected, the default behavior is to enable both discard types. and the /etc/fstab mount options discard, discard=once, or discard=pages may also be used to enable discard flags. choose your fighter 🎀
• -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. no missing-device meltdowns here 💖
• -f, --fixpgsz — reinitializes (exec mkswap) the swap space if its page size doesn't match that of the current running kernel. heads up though: mkswap(8) initializes the whole device and does not check for bad blocks. so like, it's thorough but it's not doing a background check 😭
• -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. 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 the final boss of your flags 👑

• -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. lowkey spicy 🌶️
• -s, --summary — displays swap usage summary by device. equivalent to cat /proc/swaps. > this output format is DEPRECATED in favour of --show, which provides better control on output data. so use --show, bestie, she's the upgrade.
• --show[=column...] — displays a definable table of swap areas. see the --help output for a list of available columns. customizable queen ✨
• --output-all — outputs all available columns. everything, everywhere, all at once.
• --annotate[=when] — adds an annotation to each column header name. such an annotation can be shown as a tooltip by terminals that support this feature. the optional when argument can be always, never, or auto. if the argument is omitted, it defaults to auto, which means annotations will only be used when the output goes to a terminal. so smart, so context-aware 💅
• --noheadings — do not print headings when displaying --show output.
• --raw — display --show output without aligning table columns. chaotic but honest.
• --bytes — display swap size in bytes in --show output instead of in user-friendly units. for the number girlies 🔢
• -U uuid — use the partition that has the specified uuid.
• -v, --verbose — be verbose. tell me everything 🗣️
• -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? not invited to the party.

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=.

the second field (target) 🌸

unused by swapon, and the recommended convention is to use "none".

the third field (type) 🦋

requires "swap" as the filesystem type. no substitutes, no swaps for the swap (pun intended).

the fourth field (options) 💜

it's formatted as a comma-separated list of options. all unknown options are silently ignored (she's unbothered). 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 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, and the recommended convention is to keep it empty.

the sixth field ⭐

unused by swapon, and the recommended convention is to keep it empty.

---

🔥 EXIT STATUS 🔥

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

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

the command swapoff --all returns 0 (all succeeded), 32 (all failed), or 64 (some failed, some succeeded). it's giving graded results 📊

+ the old versions before v2.36 has 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. like, she needs direct access, okay??

commands like cp(1) or truncate(1) create files with holes. these files will be rejected by swapon. not a vibe.

preallocated files created by fallocate(1) may be interpreted as files with holes too, depending of 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. old reliable fr fr 💖

Btrfs 🌳

swap files on Btrfs are supported since Linux 5.0 on files with 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. glow up ✨

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, she's doing it for your own good, bestie 🫶

---

👑 HISTORY 👑

the swapon command appeared in 4.0BSD. vintage. classic. mother.

---

💖 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>. don't be shy, they wanna hear it.

---

🌈 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/>.

---

okay that's the whole page, you ate that 🎀 this was util-linux 2.42.4, dated 2026-09-21, and it's the SWAPON(8) manual — go forth and swap responsibly, bestie 💅✨