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

Canonical page: https://fastfetch.dev/format/ · Checked against fastfetch 2.71.0 · Updated 2026-11-06 · Independent guide, not affiliated with the fastfetch-cli project.

## Playground

## 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*

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

```bash
fastfetch -h cpu-format
```

The [module explorer](/modules/) 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 numbers**Numeric 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](/modules/) 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](/customize/), 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)":

*config.jsonc*

```jsonc
{ "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:

*config.jsonc*

```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") | 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](/lab/#v271)).

## 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*

```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.0**JavaScript (`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.

---

Contact: hello@fastfetch.dev · Official project: https://github.com/fastfetch-cli/fastfetch
