Guide + tool · format strings

Format strings, with a live playground

A format string controls what a module prints. Write one below and the playground renders it exactly as fastfetch's own format engine would, using the module's real placeholder names from 2.71.0.

Checked against v2.71.0Updated 2026-11-06

Playground#

Placeholders (click to insert)
Examples
preview · sample values
Raw output (escape codes shown as \e)
config.jsonc module entry
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:

config.jsonc
{
  "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-format

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

Use names, not numbersNumeric placeholders like {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:

ModuleUseful 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:

ModuleFormatReal 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 hiddeneth0, 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#

SyntaxEffect"Arch Linux" becomes
{name:4}Cut to 4 bytes, then trim trailing spacesArch
{name:-5}Cut, trim, then add an ellipsisArch…
{name<-6}Pad, or cut to 5 and add an ellipsisArch …
{name<14}Left-align in 14 columnsArch Linux    
{name>14}Right-align in 14 columns    Arch Linux
{name|14}Center (2.64.0+)  Arch Linux  
{name<6}Padding also truncates longer valuesArch 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#

SyntaxMeaning"Arch Linux" becomes
{name~0,4}Bytes 0 to 3 (end is exclusive)Arch
{name~5}From byte 5 to the endLinux
{name~-5,-1}Negative indexes count from the endLinu
{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)":

config.jsonc
{ "type": "battery", "format": "{capacity}{?cycle-count} ({cycle-count} cycles){?}" }
Value typeCounts as "set" when
Numbergreater than 0 (so 0 and negative "not reported" sentinels are unset)
Stringnot empty
Booleantrue
Listat 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):

NotationExampleMeans
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:

config.jsonc
{
  "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")ExpectedLinuxmacOSWindows
{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.

config.jsonc
{ "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, io or debug. Load your own helpers with dofile from general.preload.lua (2.69.0+).
  • Lua support depends on how fastfetch was built: check fastfetch --list-features for a Lua entry. In our tests, the Homebrew (macOS), Scoop (Windows) and Arch builds of 2.70.0 listed Lua 5.5; the Ubuntu PPA build listed no Lua at all, so lua: formats won't run there.
QuickJS was removed in 2.70.0JavaScript (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.