# How Fastfetch Format Strings Work: Complete Guide to Custom Output

> Learn how fastfetch format strings work at runtime. Customize your terminal output with module data, conditionals, colors, and truncation.

- Repository: [fastfetch-cli/fastfetch](https://github.com/fastfetch-cli/fastfetch)
- Tags: deep-dive
- Published: 2026-03-30

---

**Fastfetch format strings are parsed at runtime by `ffParseFormatString` in [`src/common/impl/format.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/format.c), which interpolates module data, evaluates conditionals, applies ANSI colors, and handles truncation to produce fully customizable terminal output.**

Fastfetch uses a sophisticated format string system to give users pixel-perfect control over system information display. This deep dive examines how the `fastfetch-cli/fastfetch` repository implements dynamic output generation through runtime string parsing and interpolation, based on the current `dev` branch implementation.

## The Format String Processing Pipeline

The fastfetch format string engine operates through a multi-stage pipeline that transforms template strings into rendered output. Each stage is implemented in specific source files with clear separation of concerns.

### Module Data Exposure via FFformatarg

Every module populates a **`FFformatarg[]`** array with the values it can provide, such as `{pretty-name}`, `{arch}`, or `{size}`. This array construction happens inside each module's source file using the **`FF_PRINT_FORMAT_CHECKED`** macro.

For example, the OS module in [`src/modules/os/os.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/modules/os/os.c) defines which arguments are available for the format string to reference.

### Parser Entry Points: ffPrintFormat and ffParseFormatString

When rendering output, the system calls **`ffPrintFormat`** from [`src/common/impl/printing.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/printing.c). This function creates an `FFstrbuf` buffer and forwards the module's `outputFormat` along with the argument list to the core parser:

```c
ffParseFormatString(&buffer, &moduleArgs->outputFormat, numArgs, arguments);

```

*Source:* [printing.c L84–L88](https://github.com/fastfetch-cli/fastfetch/blob/dev/src/common/impl/printing.c#L84-L88)

The **`ffParseFormatString`** function in [`src/common/impl/format.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/format.c) walks the format string character by character, copying literals and extracting placeholders when encountering opening braces.

*Source:* [format.c L22–L38](https://github.com/fastfetch-cli/fastfetch/blob/dev/src/common/impl/format.c#L22-L38)

### Placeholder Parsing and Special Prefixes

When the parser encounters a `{` character, it analyzes the content based on special prefix characters. The implementation in [`src/common/impl/format.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/format.c) (lines 46–84) handles these cases through a switch-style dispatcher:

- **`?`** — *If* conditional: `{?var} … {?}` prints the interior only if `var` is set and non-zero
- **`/`** — *Not-if* conditional: `{/var} … {/}` prints only when `var` is not set or zero  
- **`#`** — *Color* change: `{#red}` injects ANSI color codes (skipped when output is piped)
- **`$`** — *Environment variable* or *constant*: `{$HOME}` or `{${1}}`
- **`:` , `<` , `>` , `~`** — *Truncation and padding*: `{name:10}` (max 10 chars), `{name<10}` (right-pad to 10), `{name>10}` (left-pad to 10), `{name~5}` (first 5 chars + ellipsis)

### Argument Resolution and Value Rendering

The **`getArgumentIndex`** function translates placeholder names (like `{size}`) or numeric shortcuts (like `{1}`) into indices into the `FFformatarg` array.

*Source:* [format.c L73–L98](https://github.com/fastfetch-cli/fastfetch/blob/dev/src/common/impl/format.c#L73-L98)

Once the matching argument is identified, **`ffFormatAppendFormatArg`** formats the value according to its type (int, uint, string, bool, list, etc.) and appends it to the output buffer.

*Source:* [format.c L9–L42](https://github.com/fastfetch-cli/fastfetch/blob/dev/src/common/impl/format.c#L9-L42)

Finally, `ffPrintFormat` writes the completed buffer to `stdout` and appends a reset escape sequence unless the output is being piped.

*Source:* [printing.c L92–L95](https://github.com/fastfetch-cli/fastfetch/blob/dev/src/common/impl/printing.c#L92-L95)

## Format String Syntax Reference

The fastfetch format string system supports comprehensive text manipulation through specific placeholder syntax:

| Feature | Syntax | Description |
|---------|--------|-------------|
| **Simple field** | `{field}` | Replaced by the value of `field` from the module's argument list |
| **If conditional** | `{?field} … {?}` | Prints inner content only if `field` is set and non-zero |
| **Not-if conditional** | `{/field} … {/}` | Prints inner content only if `field` is not set or zero |
| **Color codes** | `{#color}` | Sets ANSI color (e.g., `{#red}`, `{#bright_blue}`). Ignored with `--pipe` |
| **Environment variables** | `{$VAR}` | Inserts value of `$VAR`. Unset variables render as-is |
| **Constants** | `{${n}}` | Uses the *n*-th constant from the global constants array (set via `--set-constants`) |
| **Truncation** | `{field:10}` | Truncates to maximum 10 characters |
| **Right padding** | `{field<10}` | Left-pads with spaces to width 10 |
| **Left padding** | `{field>10}` | Right-pads with spaces to width 10 |
| **Ellipsis truncation** | `{field~5}` | Keeps first 5 characters and appends "…" if longer |
| **Substring** | `{field:5,12}` | Keeps characters 5–16 (zero-based index) |
| **Escape braces** | `{{` | Renders a literal `{` without starting a placeholder |

## Practical Command-Line Examples

### Basic Module Formatting

Display the OS pretty name followed by the architecture:

```bash
fastfetch --format "OS: {pretty-name} ({arch})"

```

### Conditional Display

Print temperature only when the module reports a valid value:

```bash
fastfetch --format "{?temperature}{temperature}°C{?}"

```

### Colorized Output

Set field-specific colors using ANSI codes:

```bash
fastfetch --format "{#green}{name}{#reset}: {#yellow}{version}{#reset}"

```

### Truncation and Padding

Limit name to 15 characters and right-pad size to 10 characters:

```bash
fastfetch --format "{name:15} {size>10}"

```

### Environment Variables

Insert shell environment values directly:

```bash
fastfetch --format "Home: {$HOME}"

```

### Custom Key Formatting

Format the key itself (the label before the value) using `--set-key`:

```bash
fastfetch --set-key "{icon} {module-name}"

```

## Core Source Files and Architecture

Understanding the format string engine requires familiarity with these key files in the `fastfetch-cli/fastfetch` repository:

- **[`src/common/format.h`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/format.h)** — Defines `FFformatarg` structure and the `FF_PARSE_FORMAT_STRING_CHECKED` helper macro
- **[`src/common/impl/format.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/format.c)** — Core parser implementing placeholder expansion, conditionals, colors, truncation, and environment variable resolution
- **[`src/common/printing.h`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/printing.h)** — Declares `ffPrintFormat` and the `FF_PRINT_FORMAT_CHECKED` macro used by modules
- **[`src/common/impl/printing.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/printing.c)** — Glue layer that builds output buffers, invokes the parser, and handles final line output
- **[`src/fastfetch.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/fastfetch.c)** — CLI handling that parses `--format` and `--set-key` options
- **`src/modules/*/*.c`** (e.g., [`src/modules/os/os.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/modules/os/os.c)) — Individual modules defining default format strings and populating `FFformatarg` arrays

These components form the complete **format-string engine** powering Fastfetch's customizable output.

## Summary

- **Fastfetch format strings** are processed at runtime by `ffParseFormatString` in [`src/common/impl/format.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/format.c), not at compile time
- **Modules expose data** through `FFformatarg` arrays filled via the `FF_PRINT_FORMAT_CHECKED` macro in each module's source file
- **Conditionals** use `{?var}` for "if set" and `{/var}` for "if not set" logic to control output flow
- **Colors** via `{#color}` inject ANSI codes automatically disabled when piping output
- **Truncation and padding** support maximum widths (`:`), right-padding (`<`), left-padding (`>`), and ellipsis truncation (`~`)
- **Environment variables** and constants are accessible through the `{$}` syntax

## Frequently Asked Questions

### What file handles the main format string parsing in Fastfetch?

The core parsing logic resides in **[`src/common/impl/format.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/format.c)**, specifically within the `ffParseFormatString` function. This file handles placeholder extraction, conditional evaluation, color injection, and string truncation. The function walks the input string character-by-character and dispatches to specialized handlers based on the prefix character found inside braces.

### How do I conditionally display a value in a fastfetch format string?

Use the **if-conditional syntax** `{?variable}content{?}`. This prints "content" only if the variable is set and non-zero. For the inverse logic (print only if unset or zero), use the **not-if conditional** `{/variable}content{/}`. These conditionals are implemented in [`src/common/impl/format.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/format.c) lines 46–84 and support nesting for complex output logic.

### Can I use environment variables in fastfetch format strings?

Yes, using the **`{$VAR}`** syntax. For example, `{$HOME}` inserts the value of the `$HOME` environment variable. If the variable does not exist in the environment, the placeholder is rendered as literal text. You can also reference constants set via `--set-constants` using `{${n}}` where *n* is the constant index.

### How do I escape curly braces in fastfetch output?

Use **double braces** `{{` to render a single literal `{` character. This prevents the parser from treating the character as the start of a placeholder. There is no specific escape sequence for closing braces `}` as the parser only recognizes opening braces as special tokens.