3 unstable releases

Uses new Rust 2024

0.2.0	May 3, 2026
0.1.0	Apr 30, 2026
0.1.0-alpha.1	Apr 28, 2026

#1729 in Unix APIs

Used in procutils

MIT/Apache

52KB
1K SLoC

free

Display amount of free and used memory in the system.

Description

Displays the total amount of free and used physical and swap memory in the system, as well as the buffers and caches used by the kernel. The information is gathered from /proc/meminfo.

Inputs

/proc/meminfo -- memory statistics including MemTotal, MemFree, MemAvailable, Buffers, Cached, SReclaimable, Shmem, SwapTotal, SwapFree, LowTotal, LowFree, HighTotal, HighFree, CommitLimit, Committed_AS

Arguments

Unit selection

These flags are mutually exclusive. If none is specified, the default unit is kibibytes (1024 bytes).

Flag	Unit	Base
`-b, --bytes`	bytes	--
`--kilo`	kilobytes	1000
`--mega`	megabytes	1000^2
`--giga`	gigabytes	1000^3
`--tera`	terabytes	1000^4
`--peta`	petabytes	1000^5
`-k, --kibi`	kibibytes (default)	1024
`-m, --mebi`	mebibytes	1024^2
`-g, --gibi`	gibibytes	1024^3
`--tebi`	tebibytes	1024^4
`--pebi`	pebibytes	1024^5

Display options

Flag	Description
`-h, --human`	Human-readable output with auto-scaled units
`--si`	Use powers of 1000 instead of 1024 (with `-h`)
`-w, --wide`	Wide output: show separate Buffers and Cache columns instead of combined buff/cache
`-l, --lohi`	Show detailed low and high memory statistics
`-L, --line`	Show output on a single line
`-t, --total`	Show a Total row (RAM + swap combined)
`-v, --committed`	Show committed memory and commit limit

Repeat options

Flag	Description
`-s, --seconds SECS`	Repeat printing every SECS seconds (accepts fractional values)
`-c, --count N`	Repeat N times then exit (if used without `-s`, prints N times with no delay)

When -s is used without -c, repeats indefinitely. When both are used, repeats N times at the given interval.

Behavior

Default table mode

Produces a table with the following columns and rows:

              TOTAL    USED    FREE  SHARED  BUFF/CACHE  AVAILABLE
Mem:       16306960 5765432 2341528  803712     8200000   10541528
Swap:       8388604  123456 8265148

Columns:

TOTAL -- total installed memory (or swap)
USED -- used memory, calculated as: TOTAL - FREE - BUFFERS - CACHE
FREE -- unused memory
SHARED -- memory used by tmpfs (Shmem from meminfo)
BUFF/CACHE -- sum of buffers and cache (includes SReclaimable)
AVAILABLE -- estimate of memory available for starting new applications

Wide mode (`-w`)

Replaces the combined BUFF/CACHE column with separate BUFFERS and CACHE columns:

              TOTAL    USED    FREE  SHARED  BUFFERS    CACHE  AVAILABLE

Line mode (`-L`)

Prints all values on a single line:

SwapUse 123456 CachUse 8200000  MemUse 5765432 MemFree 2341528

Additional rows

-l, --lohi adds Low and High memory rows (relevant on 32-bit systems)
-t, --total adds a Total row summing Mem and Swap
-v, --committed adds a Comm row showing CommitLimit, Committed_AS, and the difference

Memory calculations

cached = Cached + SReclaimable (from meminfo)
used = MemTotal - MemFree - Buffers - cached
buff/cache = Buffers + cached
swap used = SwapTotal - SwapFree

Human-readable mode (`-h`)

Automatically selects the most appropriate unit (B, Ki, Mi, Gi, Ti, Pi) for each value. Values below 10 of the selected unit are shown with one decimal place. With --si, uses powers of 1000 and suffixes B, K, M, G, T, P.

Exit codes

Code	Meaning
0	Success
1	Failure (cannot read /proc/meminfo)

Divergences from procps-ng

Column headers are UPPERCASE (TOTAL, USED, FREE, SHARED, BUFF/CACHE, AVAILABLE) rather than lowercase, matching the convention used by lsblk, lscpu, and other modern util-linux tools.
Error messages for invalid arguments use different wording.

Dependencies

~7–14MB
~269K SLoC