This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Loadavg

Print system load averages

Module type	loadavg
Default order	12 (only used by --gen-config)
Module source	src/modules/loadavg/loadavg.c
Detection source	src/detection/loadavg/ (plus src/detection/cpu/ for the expanded layout)

Prints the three standard load averages — over 1, 5 and 15 minutes. The default layout puts all three on one line; compact: false prints one line per window, with a percentage and an optional bar.

Load Average: 53.03, 20.15, 16.47

Load Average (1 min): 15.00 (150%)
Load Average (5 min): 16.41 (164%)
Load Average (15 min): 15.48 (155%)

Platform support

Platform	Implementation	Notes
Linux	cpu_linux.c, loadavg_linux.c	/proc/loadavg, with a sysinfo() fallback
Android	cpu_linux.c, loadavg_linux.c	/proc/loadavg is not readable by apps; sysinfo() is the only path
FreeBSD / NetBSD / OpenBSD / DragonFly	cpu_bsd.c, loadavg_bsd.c	sysctl({CTL_VM, VM_LOADAVG})
macOS	cpu_apple.c, loadavg_bsd.c	Same VM_LOADAVG reader
Solaris / illumos	cpu_sunos.c, loadavg_sunos.c	getloadavg()
Haiku	cpu_haiku.c	loadavg_sunos.c or loadavg_nosupport.c, chosen at configure time (see below)
GNU/Hurd	cpu_linux.c, loadavg_sunos.c	getloadavg()
Windows	cpu_windows.c, loadavg_nosupport.c	Not supported — always prints an error

Two platforms share loadavg_sunos.c, which is a one-line wrapper around the C library's getloadavg(): Solaris and GNU/Hurd. On the Hurd the Hurd's own /proc/loadavg is not used — the block compiles loadavg_sunos.c and loadavg_linux.c is not built at all there.

The Haiku row is decided by check_function_exists(getloadavg HAVE_GETLOADAVG) in the Haiku block of CMakeLists.txt (~line 1293), with libbsd added to the required libraries: if the function is present loadavg_sunos.c is compiled, otherwise loadavg_nosupport.c. Because this is a configure-time check, it cannot be expressed in the platform matrix — the same Haiku build tree can produce either binary.

Configuration

Key	Type	Default	Description
ndigits	integer 0–9	2	Digits after the decimal point in the compact layout.
compact	boolean	true	Print all three values on one line.
percent	object	{ green: 50, yellow: 80, type: 0 }	Colour thresholds and output style for the percentage.
key	string	module name	Module key. In the expanded layout this is itself a format string (see below).
keyColor	color	–	Overrides display.color.keys.
keyWidth	integer	–	Overrides display.key.width.
keyIcon	string	built-in glyph	Printed when display.key.type includes the icon bit. Any glyph works, "" prints none.
outputColor	color	–	Overrides display.color.output.
format	string	–	Custom output format (see below).
condition	object	–	Show the module only if the conditions match.

percent.type accepts the same values as display.percent.type; 0 means "inherit the global setting", 1 prints the number, 2 a multicolour bar, 3 both, and so on.

The key as a format string in the expanded layout

When compact is false and a custom key is set, the key is parsed with four variables:

Variable	Value
{index}	Window index, 0-based (0, 1, 2)
{duration}	Window length in minutes (1, 5, 15)
{icon}	The module's keyIcon value
{module-name}	The localised module name (Load Average)

{ "type": "loadavg", "compact": false, "key": "L{index}/{duration}" }

L0/1: 7.17 (72%)
L1/5: 12.67 (127%)
L2/15: 14.10 (141%)

Note that {index} starts at 0 while {duration} starts at 1. When no custom key is set, the module builds <module name> (<duration> min) itself.

Format string

Run fastfetch -h loadavg-format for the authoritative list.

Variable	Description
{loadavg1}	Load average over 1 minute
{loadavg2}	Load average over 5 minutes
{loadavg3}	Load average over 15 minutes

A format replaces the whole layout: neither compact nor percent has any effect on it, and the three values are printed by the generic format engine, which does not honour ndigits.

JSON output

{
    "type": "Loadavg",
    "result": [
        53.02978515625,
        20.1484375,
        16.47412109375
    ]
}

result is an array of three doubles, not an object — one of the few modules whose JSON result is not a map. The raw values carry full double precision, so they are much longer than the two-digit text output.

Examples

// Percentage relative to the number of online cores, one line per window
{ "type": "loadavg", "compact": false, "percent": { "type": 3, "green": 40, "yellow": 70 } }

// A single line in a custom unit
{ "type": "loadavg", "format": "1m {loadavg1} | 5m {loadavg2} | 15m {loadavg3}" }

Pitfalls

• ndigits is limited to 0–9. Anything outside that range prints Property 'ndigits' must be an integer between 0 and 9 and the layout falls back to the default of 2, so both "ndigits": 200 and "ndigits": -1 are rejected instead of quietly producing a very long or truncated number. The parser and the schema's minimum/maximum agree on the range.
• ndigits does not apply to a custom format. {loadavg1} is formatted by the shared format engine, which has its own precision — a config with ndigits: 1 and format: "{loadavg1}" still prints 13.96.
• percent does nothing in the default (compact) layout. The percentage is only computed in the compact: false branch, so a config that sets thresholds without turning compact off looks like it was ignored.
• The percentage is not CPU utilisation. It is load / cpu.coresOnline × 100, so a value above 100 means "more runnable tasks than cores", not "the CPU is over 100 % busy". On a 10-core machine a load of 15 prints (150%).
• compact: false costs an extra CPU detection. That branch calls ffDetectCPU() to learn coresOnline, which reads the CPU model, cache sizes and — on platforms that support it — frequencies. Use the compact layout if you only want the three numbers.
• Windows always fails. loadavg_nosupport.c returns Not supported on this platform, so the module prints an error line (or nothing at all when display.showErrors is false).
• GNU/Hurd does not read the Hurd's own /proc/loadavg. That block compiles loadavg_sunos.c and never builds loadavg_linux.c, so the Hurd reports whatever getloadavg() returns — the same source Solaris uses. A Hurd system whose libc cannot provide three samples reports getloadavg() failed instead. The read(/proc/loadavg) failed wording Uptime uses for its own dead end therefore never appears on the Hurd any more.
• Load average is a host-wide value. Inside a container it reports the host's load, and in a container with a private, restricted /proc it may be missing entirely — the module then silently falls back to sysinfo(), which is not namespaced either.

Implementation

Linux and Android

ffDetectLoadavg() reads /proc/loadavg with ffReadFileData() (63-byte cap) and pulls the first three whitespace-separated values out with sscanf("%lf%lf%lf", …); it accepts the result only when all three conversions succeed. The file is read rather than obtained from the getloadavg() libc call on purpose — the comment cites issue #620 and container compatibility.

When that fails, Linux falls back to sysinfo(&si) and divides each si.loads[i] by 1 << SI_LOAD_SHIFT. Android skips the /proc read because the file is not readable by apps, so sysinfo() is its only path. GNU/Hurd no longer compiles this file at all.

ndigits is parsed with the shared ffJsonConfigParseUInt32() helper, bounded to 9, which is what makes an out-of-range value an error instead of a (uint8_t) truncation.

FreeBSD, NetBSD, OpenBSD, DragonFly and macOS

sysctl({CTL_VM, VM_LOADAVG}) fills a struct loadavg, and each entry is divided by the kernel-supplied fscale rather than by a fixed constant, so the result stays correct on platforms that scale the raw counters differently.

Solaris, GNU/Hurd, and (on Haiku) the libbsd path

getloadavg(result, 3) is used directly, with the <sys/loadavg.h> include guarded by __has_include so a libc without that header still compiles against <stdlib.h>. Anything other than exactly three samples is reported as getloadavg() failed. The same file serves Haiku whenever libbsd provides the symbol.

Windows

There is no implementation: loadavg_nosupport.c returns the error string Not supported on this platform. The module is still registered, so it appears in --list-modules and in the default structure on Windows, where it renders an error line.

Shared

The three values are stored in a double[3] that the caller pre-fills with 0.0 / 0.0 (NaN), so a detection that returns success without writing anything is visible in the output rather than being reported as zeros. ffPrintLoadavg() and ffGenerateLoadavgJsonResult() each call ffDetectLoadavg() themselves; a run uses one or the other, never both.