Fastfetch documentation

1. Getting started

Run fastfetch with no configuration and it prints your OS, hardware and desktop details next to a logo. Everything on this page applies to fastfetch 2.69.0; commands were run against a 2.69.0 build, and configs were validated against its JSON schema. Need to install it first? See the install guide for every platform.

Basic usage

A preset name is looked up like this: first as a file path (.jsonc is appended when there is no extension), then in fastfetch/ inside your config directories, then in fastfetch/presets/ inside the data directories, then next to the fastfetch executable. Use -c - to read a config from standard input and -c none to skip loading any config. fastfetch --list-data-paths prints the preset and logo search paths.

2. Building from source

Fastfetch builds with CMake and a C23-capable compiler: GCC 13 or newer, or Clang 16 or newer. Since 2.67.0 this is the minimum, and the build stops early with a clear message on older compilers, so Debian 12 (GCC 12) cannot build current releases from source; use a prebuilt binary from GitHub Releases there. pkg-config is recommended so optional libraries are detected. MSVC is not supported.

Linux, macOS and BSD

cmake --build . without --target fastfetch also builds flashfetch, a benchmark binary you do not need. If the headers for an optional library are missing, the build simply leaves that feature out instead of failing. Run ./fastfetch --list-features afterwards to see what was compiled in.

Useful CMake options

Windows (MSYS2 CLANG64)

Install MSYS2, open the MSYS2 / CLANG64 shell (not plain MSYS2 / MSYS), install the toolchain, then follow the Linux steps above. Use CLANGARM64 and the matching mingw-w64-clang-aarch64-* packages for ARM64.

Optional libraries and dynamic loading

On Linux the only hard requirements are libc, libdl, libm and libpthread, plus the Linux headers at build time. Everything else is loaded at run time when present, and the matching module or feature quietly degrades when it is not. Examples:

The complete list is in the official Dependencies wiki page. On Windows 8.1 the Universal C Runtime must be installed manually and a terminal with ANSI escape support (such as ConEmu) is needed; Windows 7 is not supported.

3. How fastfetch works and how to keep it fast

Fastfetch is a C program that asks the operating system directly instead of running helper commands. On Linux it reads files such as /proc and /sys, on macOS it uses sysctl, IOKit and system frameworks, and on Windows it uses native Win32 and registry APIs. Neofetch, in contrast, is a Bash script that starts many external programs. Optional libraries are loaded on demand (see above), so a missing one never stops the program.

Measure first, then tune

In practice the usual causes of a slow run are modules that talk to the network (publicip, weather), command modules that run slow shell scripts, and disks on unresponsive network mounts. Remove those modules and run --stat again.

4. Logos, images and colors

Fastfetch ships 540 built-in ASCII logos and can draw real images in terminals that support a graphics protocol.

Built-in logos

Most distributions have a _small variant (for example arch_small); a few, such as Windows, do not. --logo-position auto (new in 2.69.0) moves a wide logo above the output when fewer than 32 columns would remain for text; the default is still left.

Image logos

Point --logo at an image and choose the protocol your terminal speaks with --logo-type. On Linux and BSD, fastfetch must have been built with ImageMagick; on Windows, macOS and Android it uses the operating system's image support (since 2.69.0, Windows Terminal shows sixel logos out of the box).

Image logos are cached; the cache is invalidated when the source file changes but not when you only change --logo-type, so run --logo-cache regen after switching types. (--logo-recache was replaced by --logo-cache in 2.69.0.) Set logo.animationFrame to 0 to play an animated GIF/APNG with the kitty type. If an image does not show, add --show-errors to see why. Apple's Terminal.app supports neither sixel nor the kitty or iTerm protocols.

Custom logos, padding and random images

{
  "logo": {
    "type": "file",
    "source": "~/logos/mylogo.txt",
    "padding": { "top": 1, "left": 2, "right": 4 },
    "color": { "1": "blue", "2": "light_white" }
  }
}

• file prints a text file and replaces $1 to $9 with the colors from logo.color (write $$ for a literal $); file-raw and data-raw print exactly what they are given.
• Random logo: a wildcard such as "source": "~/logos/*.png" makes fastfetch pick one matching file at random on each run (Linux, macOS, BSD).
• Command output as logo: { "type": "command-raw", "source": "pokeget random --hide-name" } works in a JSONC config only.
• Disable the logo: --logo none, or "logo": null in the config.
• Paths may use ~ and environment variables. On Linux, quote or escape spaces in paths; on Windows use %USERPROFILE% syntax.

Colors

Everywhere a color is accepted (--color-keys, display.color.keys, logo.color, {#...} in format strings) you can use:

Run fastfetch -h color for the named-color list. There is no background-color prefix; write the ANSI code (for example 44) instead. The colors module draws your terminal's 16-color palette, which is handy for checking a theme.

5. Configuration file (JSONC)

Fastfetch reads JSONC: JSON with // comments and trailing commas. A config.json5 in the same folder is also understood. Unknown keys are reported as errors, which makes typos easy to find.

Where fastfetch looks for config.jsonc

The first file found wins. Run fastfetch --list-config-paths to see the exact folders on your machine; a (*) marks the one that exists.

The current directory is not searched, so a config.jsonc next to where you run the command is ignored unless you pass it with -c. In each folder fastfetch also accepts fastfetch/config.json5.

A complete starter config

Add the $schema line and editors such as VS Code and Helix give you autocomplete and validation.

{
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json",
  "logo": {
    "type": "auto",
    "padding": { "right": 2 }
  },
  "display": {
    "separator": ": ",
    "color": { "keys": "blue" },
    "key": { "width": 12 },
    "percent": { "type": 3 }
  },
  "modules": [
    "title",
    "separator",
    "os",
    "host",
    "kernel",
    "uptime",
    "packages",
    "shell",
    "display",
    "cpu",
    "gpu",
    "memory",
    "disk",
    "battery",
    "break",
    "colors"
  ]
}

The display block

The value is a bit mask (number = 1, bar = 2, hide others = 4, color the number = 8, single-color bar = 16). Individual modules such as memory and disk can override it with their own percent object, for example { "type": 3, "green": 30, "yellow": 70 }. Module options exist only in the JSON config; the old --<module>-<option> command-line flags were removed in 2.52.0.

Bundled presets

Load one with fastfetch -c <name>. Browse the presets folder on GitHub, or copy one into your config folder and edit it.

Themes and dotfiles

Community themes (Catppuccin, Nord, Tokyo Night, Gruvbox and so on) are ordinary config files. Keep yours in your dotfiles repository and load it by path with fastfetch -c ~/dotfiles/fastfetch/nord.jsonc, or symlink it to ~/.config/fastfetch/config.jsonc. Our themes and dotfiles guide explains how to adapt one and what to check before trusting a downloaded config (the command module and command-raw logos run shell commands).

6. Format strings

The format option of a module is a template with {placeholders}. List a module's placeholders with fastfetch -h <module>-format.

{
  "type": "cpu",
  "format": "{name} ({cores-physical}C/{cores-logical}T) @ {freq-max}"
}

Use named placeholders. Numbered ones ({1}, {2}) are deprecated because their order can change between releases. A placeholder that cannot be resolved (for example a typo) is printed as written, which makes mistakes easy to spot. Write {{ to print a literal {.

Truncating, padding and slicing

Conditional text

{
  "type": "battery",
  "format": "{capacity}{?cycle-count} ({cycle-count} cycles){?}"
}

• {?name}text{?} prints text only when the variable is set; {/name}text{/} prints it only when the variable is not set.
• For numbers, “set” means greater than zero, so a 0 counts as not set. Use the conditional form for values that some systems do not report, because a bare placeholder can print a raw sentinel such as -2147483648.
• {-} ends the format string; everything after it is discarded.

Colors inside format strings

{
  "type": "title",
  "format": "{#bold_green}{user-name}{#}@{##58A6FF}{host-name}{#}"
}

{#color} starts a color and {#} resets it; the color can be any form from the colors table above. For a hex color write two hashes: {##FF8800}. {#keys}, {#title}, {#output} and {#separator} reuse the configured colors. In JSON, a raw escape must be written as \u001b, never \e.

Environment variables and constants

{
  "display": { "constants": ["prod"] },
  "modules": [
    { "type": "custom", "key": "Env", "format": "{$1} @ {$HOME}" }
  ]
}

{$NAME} inserts an environment variable. {$1} is the first entry of display.constants and {$-1} the last. If a variable is not set, or is only a shell variable that was never exported (HOSTNAME and USER often are not), the placeholder is printed as written. For names, prefer the title module's {user-name} and {host-name}.

Lua scripting (advanced)

Since 2.64.0 a format string that starts with lua: is run as Lua (5.3 to 5.5). The module's values arrive as a table, and the script must return a string; returning nothing hides the module. fastfetch --list-features shows whether your build includes Lua. QuickJS (JavaScript) scripting is deprecated and off by default as of 2.69.0.

{
  "type": "title",
  "format": "lua:local a = ...; return string.format('Hello %s@%s', a.userName, a.hostName)"
}

7. Module reference (76 modules)

Fastfetch 2.69.0 has 76 modules. In modules you can write a module as a string ("cpu") or as an object ({ "type": "cpu", "key": "Processor", "format": "..." }). Every module accepts key, keyColor, keyWidth, keyIcon, outputColor and format; set key to a single space to hide a key. Run fastfetch --list-modules for the list in your build and fastfetch -s <a>:<b> --format json to see all the raw data a module produces.

Hardware and firmware 31

Operating system and shell 17

Desktop and appearance 9

Network and media 8

Graphics APIs 3

Layout and custom output 8

Placeholders for the most-used modules

Names below come from fastfetch -h <module>-format in 2.69.0. Several more exist for each module.

The desktop modules are called de and wm in config files, and their default keys are “DE” and “WM”. The command module runs a shell command and shows its output, and custom prints any string, so almost anything can be added to the output.

{
  "type": "command",
  "key": "Updates",
  "text": "checkupdates | wc -l"
}

Not on the page yet? Every module has a page in the official wiki, for example Modules-GPU, with its platform support and all options.

8. Command-line options and exit codes

Module settings (CPU temperature, disk filters and so on) are set in the config file only; the old per-module command-line flags such as --gpu-driver-specific no longer exist.

Exit codes

Fastfetch exits with 0 on success. Errors such as an unknown option or a config file that cannot be found exit with a non-zero status, and the value is not always 1 (an unknown option currently yields 144, a missing config 158). In scripts, test for non-zero rather than for exactly 1. Modules that cannot detect something are skipped; they do not change the exit code. Use --show-errors to see them.

JSON output for scripts and tools

--format json prints an array with one object per module, with raw numbers (bytes, MHz) instead of formatted text. Never parse the colored text output. Combine with -s to limit work to the modules you need:

[
  { "type": "CPU",    "result": { "cpu": "…", "cores": { "physical": 4, "logical": 4 }, "…": "…" } },
  { "type": "Memory", "result": { "total": 16876494848, "used": 484343808 } }
]

In 2.69.0, modules chosen with --structure honor their options from the JSON config. For AI agents and automation, see also the AGENTS.md guide and the llms.txt index of this site.

Migrating from Neofetch

Neofetch was archived in April 2024. Its Bash config cannot be converted automatically, but the concepts map directly:

A step-by-step comparison is on the homepage: Neofetch to Fastfetch migration.

9. Troubleshooting

Start with fastfetch --show-errors; most problems print a reason there.

Output is black and white, or the logo is missing

Cause: stdout is not a terminal (a pipe, a file, some wrappers), so fastfetch switches to plain output.
Fix: run fastfetch --pipe false. In a shell startup file, see the Powerlevel10k note below.

Icons show as question marks or boxes

Cause: the font does not contain the glyphs. Fastfetch's default output is plain text; icons appear only with display.key.type set to icon/both or in community configs that use Nerd Font symbols.
Fix: install a Nerd Font and select it in your terminal, or switch back to "key": { "type": "string" }.

An image logo does not display

Cause: the terminal does not support the chosen protocol, fastfetch was built without image support, or the file cannot be read. When it fails, fastfetch falls back to the built-in logo.
Fix: run with --show-errors; try --logo-type chafa (works almost everywhere) or the protocol your terminal documents; set --logo-width and --logo-height if the image overlaps text; use --logo-cache regen after changing the type. Check --list-features for ImageMagick/chafa on Linux.

Adding fastfetch to ~/.bashrc breaks scp, sftp or rsync

Cause: non-interactive SSH sessions also read ~/.bashrc; extra text on stdout corrupts the file-transfer protocol (errors such as “Received message too long”).
Fix: run it in interactive shells only: [[ $- == *i* ]] && fastfetch.

Powerlevel10k instant prompt shows a warning or no colors

Cause: with the instant prompt enabled, console output during zsh startup must be avoided or produced before the instant-prompt block.
Fix: put fastfetch above the instant-prompt block in ~/.zshrc, or use --pipe false if colors are missing.

My GPU shows as "Device 1234" or the wrong name

Cause: an outdated PCI ID database.
Fix: update hwdata/pci.ids (and amdgpu.ids for AMD), or add { "type": "gpu", "driverSpecific": true } to the modules to read names, memory and clocks from the vendor driver. With detectionMethod you can choose which backend is tried first. On hybrid laptops, a powered-off discrete GPU may not be listed until it is used.

CPU temperature is missing

Cause: the module does not show temperature unless you enable it, and the kernel must expose a sensor.
Fix: use { "type": "cpu", "temp": true }. On Linux check that /sys/class/hwmon has a k10temp (AMD) or coretemp (Intel) entry; tempSensor can pick a specific one. Virtual machines often have none.

Package counts are missing or lower than expected

Cause: a package manager is not supported by your build, is skipped via PACKAGES_DISABLE_*, or its database cannot be read (for example sqlite3/librpm support missing for rpm on openSUSE).
Fix: check fastfetch --list-features, use --show-errors, and read {all} or per-manager placeholders in the packages format.

Fastfetch is slow

Run fastfetch --stat to see the time per module, remove the slow ones (usually network or custom command modules), and lower general.processingTimeout if a child process hangs. Measure the total with hyperfine 'fastfetch --pipe false'.

Build error about C23 or an unsupported compiler

Cause: the compiler is older than GCC 13 or Clang 16.
Fix: install a newer toolchain, or download a prebuilt binary from GitHub Releases (this is the case on Debian 12).

Wrong or missing information on an exotic system

Check the official Support Status page, then search or ask in Discussions. For a confirmed bug, open an issue upstream and attach the output of fastfetch -c all --pipe true --show-errors.