Playground#
Edit the sample values (e.g. empty one to test {?…} conditionals)
The engine is a line-by-line port of format.c from 2.71.0, including that release's fixes for nested conditionals and substring ranges. It passes every case in 2.71.0's own format test suite that has no escape codes in the value, and it matched the real fastfetch 2.71.0 release on all 36 of our test strings on Linux, macOS and Windows (see the test). Values are from one fictional laptop. lua: scripts are not executed here.
Basic syntax#
Placeholders are names in curly braces. Set a module's format in your config, and fastfetch replaces each placeholder with the detected value:
{
"modules": [
{ "type": "title", "format": "{user-name}@{host-name}" },
{ "type": "cpu", "format": "{name} ({cores-logical} threads)" }
]
}Every module has its own placeholders. Print them with fastfetch -h <module>-format, for example:
fastfetch -h cpu-formatThe module explorer lists them all (558 across 71 modules). A placeholder that can't be resolved, such as a typo, is printed as written, so mistakes are easy to spot. Placeholder names are matched case-insensitively.
{1} still work, but the wiki marks them deprecated: their order has changed between releases (2.62.0 and 2.65.0 reordered the Packages arguments), which silently breaks configs. Named placeholders stay stable.Placeholders you'll use most#
From the 2.71.0 source. The module explorer has the full list with descriptions:
| Module | Useful placeholders |
|---|---|
| Title | {user-name} {host-name} {full-user-name} {cwd} {user-shell} |
| OS | {pretty-name} {name} {version} {codename} {arch} |
| Kernel | {sysname} {release} {arch} |
| Uptime | {days} {hours} {minutes} {formatted} {boot-time} |
| Packages | {all} plus one per manager: {pacman} {dpkg} {rpm} {flatpak-system} {brew} {nix-system}… |
| Shell / Terminal | {pretty-name} {version} {exe-name} |
| Display | {width} {height} {refresh-rate} {scale-factor} {inch} {name} |
| CPU | {name} {cores-physical} {cores-logical} {freq-max} {temperature} {march} |
| GPU | {name} {vendor} {driver} {type} {temperature} {dedicated-total} |
| Memory | {used} {total} {percentage} {percentage-bar} |
| Disk | {size-used} {size-total} {size-percentage} {size-free} {filesystem} {mountpoint} {days} {create-time} |
| Battery | {capacity} {status} {cycle-count} {time-formatted} |
| LocalIp | {ipv4} {ipv6} {ifname} {mac} |
Format strings we ran, and what they printed#
These are taken from the customization recipes, which ran on Linux, macOS and Windows. The output column is what the Ubuntu runner printed:
| Module | Format | Real output |
|---|---|---|
| OS | {pretty-name} | Ubuntu 24.04.5 LTS (Noble Numbat) |
| Kernel | {release} | 7.0.0-1017-azure |
| Memory | {used} / {total} | 1.01 GiB / 15.61 GiB |
Disk on / | {days} days (installed {create-time:10}) | 12 days (installed 2026-10-21) |
| LocalIp | {ifname}, address hidden | eth0, address hidden |
Note {create-time:10} in the fourth row: it cuts the full timestamp down to its first ten bytes, the date. That's the truncation syntax explained next.
Truncate, pad and align#
| Syntax | Effect | "Arch Linux" becomes |
|---|---|---|
{name:4} | Cut to 4 bytes, then trim trailing spaces | Arch |
{name:-5} | Cut, trim, then add an ellipsis | Arch… |
{name<-6} | Pad, or cut to 5 and add an ellipsis | Arch … |
{name<14} | Left-align in 14 columns | Arch Linux |
{name>14} | Right-align in 14 columns | Arch Linux |
{name|14} | Center (2.64.0+) | Arch Linux |
{name<6} | Padding also truncates longer values | Arch L |
Lengths count bytes, not characters, so a multi-byte character such as é counts as two. A negative width adds … when the value is cut. With : the cut value is trimmed first and the ellipsis appended; with <, > and | the ellipsis takes the place of the last byte.
Slice part of a value#
| Syntax | Meaning | "Arch Linux" becomes |
|---|---|---|
{name~0,4} | Bytes 0 to 3 (end is exclusive) | Arch |
{name~5} | From byte 5 to the end | Linux |
{name~-5,-1} | Negative indexes count from the end | Linu |
{name~2,} | Trap: an empty end means 0, so nothing prints | (empty) |
{name~0,-20} | An end before the start prints nothing (2.71.0+; older versions printed the rest of the value) | (empty) |
{name~20,30} | A range that starts past the end prints nothing (2.71.0+; older versions printed the placeholder as is) | (empty) |
Show text only when a value exists#
{?x}…{?} prints its contents only if x is set. {/x}…{/} prints only if it is not. This is how you avoid lines like "(0 cycles)":
{ "type": "battery", "format": "{capacity}{?cycle-count} ({cycle-count} cycles){?}" }| Value type | Counts as "set" when |
|---|---|
| Number | greater than 0 (so 0 and negative "not reported" sentinels are unset) |
| String | not empty |
| Boolean | true |
| List | at least one entry |
Conditionals can be nested: {?1}A{?2}B{?}C{?}D prints D when value 1 is empty, whatever value 2 is. Before 2.71.0 a skipped block ended at the first {?} (or {/}) it met, including one that belonged to a nested conditional, so that example printed C{?}D. A conditional whose argument doesn't exist, such as {?9} in a module with fewer values, is not a block at all and is printed as text.
{-} stops formatting, so everything after it is dropped. {{ prints a literal {; there is no escape for }, which only needs one when it would close a placeholder.
Colors#
{#…} switches color and {#} resets. Fastfetch accepts four color notations (wiki: Color Format Specification):
| Notation | Example | Means |
|---|---|---|
| Named, with optional prefixes | {#bold_red}, {#underline_light_cyan} | Prefixes: bold_ bright_ dim_ italic_ underline_ blink_ inverse_ hidden_ strike_ reset_ |
| ANSI SGR codes | {#4;35}, {#38;5;208} | Anything that goes between ESC[ and m |
| Hex RGB (2.42.0+) | {##ff8800}, {##f80} | Note the double # inside a format string |
| xterm-256 (2.57.0+) | {#@208} | Same as 38;5;208 |
The keywords {#keys}, {#title}, {#output} and {#separator} reuse the colors set in display.color. There is no named background color; use a code such as 44. All color codes are dropped when output is piped.
Constants and environment variables#
{$1} inserts the first entry of display.constants, and {$-1} the last. {$HOME} inserts an environment variable. Constants are handy for repeated decorations:
{
"display": { "constants": ["──────────────"] },
"modules": [
{ "type": "custom", "format": "┌{$1}┐" },
{ "type": "os", "key": "│ OS" },
{ "type": "custom", "format": "└{$1}┘" }
]
}Keys: hide, rename, format#
"key": "Distro"renames a key. Keys are format strings too, so"key": "{#cyan}Distro{#}"works."key": " "(exactly one space) hides the key. An empty""means "use the default".- An empty
"format": ""also means "use the default". A format that evaluates to nothing still prints the key.
Checked against the real fastfetch#
The playground at the top of this page reimplements fastfetch's format engine in JavaScript. To make sure it matches, we ran the same 20 format strings through real fastfetch 2.70.0 on Linux, macOS and Windows, with a Command module printing "Arch Linux". All three agreed with the expected output in every case:
| Format (value "Arch Linux") | Expected | Linux | macOS | Windows |
|---|---|---|---|---|
{result:4} | 'Arch' | ✓ | ✓ | ✓ |
{result:-5} | 'Arch…' | ✓ | ✓ | ✓ |
{result<-6} | 'Arch …' | ✓ | ✓ | ✓ |
{result<14} | 'Arch Linux ' | ✓ | ✓ | ✓ |
{result>14} | ' Arch Linux' | ✓ | ✓ | ✓ |
{result|14} | ' Arch Linux ' | ✓ | ✓ | ✓ |
{result<6} | 'Arch L' | ✓ | ✓ | ✓ |
{result~0,4} | 'Arch' | ✓ | ✓ | ✓ |
{result~5} | 'Linux' | ✓ | ✓ | ✓ |
{result~-5,-1} | 'Linu' | ✓ | ✓ | ✓ |
{result~2,} | '' | ✓ | ✓ | ✓ |
{{result} | '{result}' | ✓ | ✓ | ✓ |
{nope} | '{nope}' | ✓ | ✓ | ✓ |
{result}{-}zzz | 'Arch Linux' | ✓ | ✓ | ✓ |
{$1} | '───' | ✓ | ✓ | ✓ |
{$FFLAB} | 'from-env' | ✓ | ✓ | ✓ |
{1} | 'Arch Linux' | ✓ | ✓ | ✓ |
{}{} | 'Arch Linux{}' | ✓ | ✓ | ✓ |
{?result}yes{?}{/result}no{/} | 'yes' | ✓ | ✓ | ✓ |
[{result:20}] | '[Arch Linux]' | ✓ | ✓ | ✓ |
On 2026-11-06 we repeated those 20 strings with the official 2.71.0 release and added 16 that exercise the 2.71.0 fixes: nested conditionals, out-of-range substrings, and numbers too big for 32 bits. 2.71.0 matched the playground on all 36, on all three systems. 2.70.0 got the new ones wrong exactly as described above, for example {/1}A{/1}B{/}C{/}D printed C{/}D instead of D (details).
Lua scripting#
A format that starts with lua: runs as a Lua script (Lua 5.3 to 5.5; not 5.1 or LuaJIT). The module's values arrive in ..., and the script must return a string; returning nil hides the module.
{ "type": "title", "format": "lua:local a = ...; return string.format('Hello %s@%s', a.userName, a.hostName)" }- One interpreter is shared by all modules, so a module can store a value for a later one.
json_encode(t, true)is provided for inspecting what a module passes:"lua:return json_encode(..., true)".- There is no
require,os,ioordebug. Load your own helpers withdofilefromgeneral.preload.lua(2.69.0+). - Lua support depends on how fastfetch was built: check
fastfetch --list-featuresfor aLuaentry. In our tests, the Homebrew (macOS), Scoop (Windows) and Arch builds of 2.70.0 listedLua 5.5; the Ubuntu PPA build listed no Lua at all, solua:formats won't run there.
qjs:) format scripts were deprecated in 2.69.0 and removed in 2.70.0. A qjs: format now prints as literal text. Port those scripts to Lua.