Fastfetch Complete Documentation

1. Getting Started

Fastfetch is designed to provide immediate, comprehensive system information with zero prerequisite configuration. Running the bare executable automatically queries your CPU, GPU, memory, operating system kernel, desktop environment, and uptime, pairing the metrics with your distribution or OS logo.

Basic Usage

To run Fastfetch with default system detection, execute the binary in any terminal emulator:

To test different presentation presets without altering your primary configuration file, use the --config (or -c) flag:

2. Building Fastfetch from Source

Fastfetch uses CMake as its primary build system and requires a standard C99/C11 compiler (GCC or Clang). MSVC on Windows is not supported due to differences in C99 syntax support; Windows builds use MSYS2 Clang64.

Linux & macOS Compilation Steps

Ensure cmake, pkg-config, and build tools are installed before proceeding:

Windows Compilation (MSYS2 CLANG64)

On Windows, install MSYS2, open the MSYS2 / CLANG64 environment terminal, and install the build toolchain:

Optional Dependencies & Dynamic Loading

Fastfetch employs dynamic library loading (dlopen on Unix, LoadLibrary on Windows). If an optional library header was missing during build time or the library is not installed on the end-user's operating system, Fastfetch gracefully disables that specific module without crashing or aborting execution.

3. Architecture & Performance Engineering

Fastfetch was engineered from the ground up in native C to eliminate the computational latency of interpreted shell scripts. While Neofetch relied on Bash loops and external utility invocations (spawning grep, sed, awk, xrandr, and wmic up to 200 times per execution), Fastfetch achieves sub-millisecond execution times through three core architectural principles:

• Direct Syscall & API Integration: Reads directly from /sys, /proc, and /dev on Linux, Mach kernel and IOKit on macOS, and Win32 / WMI on Windows.
• Asynchronous Multithreading: Heavy hardware modules (such as disk I/O, GPU query via Vulkan, and package manager indexing) execute concurrently on separate worker threads.
• Lazy Library Loading: Libraries such as Vulkan, OpenCL, Wayland, D-Bus, and Chafa are loaded dynamically only if requested in the configuration.

Performance Tuning Options

In environments with slow network drives or complex WMI providers, you can optimize execution speed further:

4. Display & Logo System

Fastfetch features the most extensive logo rendering engine of any CLI fetch tool, supporting over 300 built-in ASCII distributions and multiple modern terminal image protocols.

ASCII Distro Logos

To list all 300+ built-in ASCII logos available in your binary, run:

Modern Graphical Image Protocols

To render actual image files (PNG, JPEG, WebP) directly inside your terminal, set the --logo-type parameter:

Custom Logos, File Paths & Padding

Fastfetch allows loading custom ASCII art files, raw text files, or overriding logo padding and dimensions. In your config.jsonc:

To completely suppress logos in scripts or compact views, pass --logo none or set "logo": { "type": "none" } in your configuration.

Color Customization & 16-Color Palette

Fastfetch allows overriding logo colors, key label colors, and output values using either standard color names (black, red, green, yellow, blue, magenta, cyan, white) or ANSI 256-color / 24-bit RGB codes. The colors module displays the terminal emulator's 16-color palette bar, useful for verifying terminal color themes.

5. Configuration System (JSONC)

Fastfetch uses JSONC (JSON with comments) for configuration, providing structured syntax and editor intelligence.

Configuration Search Paths

Fastfetch looks for configuration files in the following hierarchical order:

1. Path provided via the -c / --config <path> CLI flag.
2. Relative to current working directory (./config.jsonc).
3. $XDG_CONFIG_HOME/fastfetch/config.jsonc (defaults to ~/.config/fastfetch/config.jsonc).
4. On Windows: %USERPROFILE%\.config\fastfetch\config.jsonc or %APPDATA%\fastfetch\config.jsonc.
5. System global presets: /etc/fastfetch/config.jsonc or /usr/share/fastfetch/presets/.

Annotated Configuration Example

{
  // Fastfetch JSON Schema for live autocomplete and type validation
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json",
  "logo": {
    "type": "auto",
    "source": "arch",
    "padding": { "top": 0, "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"
  ]
}

Display Options, Bars & Formatting

The display configuration block manages output formatting across all modules. You can configure key width alignment, key-value separators, and percentage bar graphics:

Official Built-in Presets

Fastfetch bundles official presets simulating other fetch tools or targeted use cases. Load any preset with fastfetch -c <preset>:

• neofetch.jsonc: Exact replica of classic Neofetch layout, module order, and formatting.
• all.jsonc: Diagnostic preset displaying all 75+ modules simultaneously.
• archey.jsonc: Archey-style visual arrangement.
• paleofetch.jsonc: Ultra-minimalist fetch preset.
• ci.jsonc: Optimized for headless continuous integration runners and build logs.

Themes, Community Presets & Dotfiles

Custom themes and presets allow you to style Fastfetch to match popular color schemes such as Catppuccin, Nord, Tokyo Night, Dracula, and Gruvbox.

To manage custom presets in your personal dotfiles repository, place JSONC configuration files into ~/.config/fastfetch/presets/ (or directly inside ~/.config/fastfetch/). You can then invoke them by filename:

6. Format Strings & Text Manipulation

Fastfetch supports a robust format string engine that lets you customize the exact values and layout of any module. Placeholders are enclosed in curly braces (e.g. {name}).

Named Arguments

Always prefer named arguments over deprecated numeric indices. To see all supported format arguments for any module, invoke fastfetch -h <module>-format:

Padding, Truncation & Slicing Syntax

Conditional Expressions

Conditionally render text depending on whether a variable is non-empty:

Color Codes & Text Styling in Format Strings

Format strings support dynamic color codes using {#1} through {#9} to bind with your theme colors, standard ANSI escape sequences (encoded in JSON as \u001b[32m), and the termination reset marker {-}:

Display Constants & Environment Variables

Fastfetch allows embedding custom display constants and operating system environment variables directly inside module format strings. Access any live environment variable using the $ prefix inside curly braces (e.g. {$USER}, {$HOSTNAME}, or {$XDG_CURRENT_DESKTOP}):

Additionally, custom indexed constants configured via "display": { "constants": ["ServerAlpha", "Production"] } can be referenced as {$1} and {$2} across all modules to maintain clean DRY configurations.

7. Complete 75+ Module Catalog

Fastfetch supports over 75 built-in hardware and software detection modules. Each module can be declared as a simple string name or as a configured JSON object with custom keys, colors, and format strings.

Hardware & System Processors

Operating System, Kernel & Packages

Media, Network & Environment

8. CLI Options & Exit Status Reference

Exit Codes

Fastfetch returns 0 on successful completion. Any unexpected error or unhandled invalid parameter results in a non-zero exit code (1).

Developer Integration & JSON Output

Developers and automation engineers can integrate Fastfetch into shell scripts, web dashboards, and monitoring tools by requesting JSON formatted output via fastfetch --format json. The structured JSON contains complete key-value arrays with unrounded bytes, raw clock frequencies, and hardware device trees.

Neofetch to Fastfetch Migration Guide

Following the official archival of Neofetch in 2024, Fastfetch serves as the high-performance, drop-in successor. Most common Neofetch configurations and arguments map directly to Fastfetch concepts:

9. Troubleshooting & Known Issues

1. Execution Takes 2–3 Seconds on Windows

Cause: On Windows, initializing Windows Management Instrumentation (WMI) and the underlying DCOM service host during the very first invocation introduces cold-start latency.
Fix: In your config.jsonc, set a processing timeout limit: "general": { "processingTimeout": 500 }. On desktop PCs without a battery, remove the battery module to skip slow WMI hardware polling. Fastfetch queries native Win32 registry APIs for CPU, memory, and OS data in sub-5ms.

2. Icons Appear as Question Marks or Empty Boxes

Cause: Your terminal font does not contain the Nerd Font and Powerline glyphs mapped to hardware symbols.
Fix: Install a patched Nerd Font and configure your terminal emulator to use it:

3. High-Resolution Image Logo Fails to Display

Cause: The active terminal does not support the requested graphics protocol (e.g. Kitty or Sixel).
Fix: Explicitly declare your supported protocol via --logo-type kitty or --logo-type sixel. If using Windows Terminal, Alacritty, or standard macOS Terminal.app, install chafa and use --logo-type chafa, which converts image files into Unicode half-block characters compatible with all terminals.

4. Adding Fastfetch to ~/.bashrc Breaks Remote Login (SCP / SFTP)

Cause: Non-interactive sessions (such as remote file transfers using SCP / SFTP, rsync, or automated CI Git hooks) source ~/.bashrc but require a clean stdout stream strictly reserved for protocol packets. Printing Fastfetch terminal banners causes SSH client crashes with "Received message too long" or "Protocol error".
Fix: In ~/.bashrc, ensure Fastfetch is guarded with an interactive shell check:

5. Package Manager Counts Are Missing or Inaccurate

Cause: Fastfetch counts packages by inspecting local package databases directly (e.g. /var/lib/pacman/local/, /var/lib/dpkg/status, Homebrew cellar, Flatpak, and Snap). If package databases are locked by another package manager instance (such as /var/lib/pacman/db.lck or /var/lib/dpkg/lock-frontend) or environment variables are not exported, some package managers may be skipped.
Fix: Ensure Homebrew is exported in your shell PATH (eval "$(/opt/homebrew/bin/brew shellenv)"). For Flatpak, ensure user read access to /var/lib/flatpak/app and ~/.local/share/flatpak/app.

6. CPU Temperature Shows N/A or Is Missing on Linux

Cause: Hardware sensor kernel drivers (k10temp for AMD Ryzen or coretemp for Intel Core) are not loaded, or the current user lacks read permissions to /sys/class/hwmon/.
Fix: Install lm_sensors and run sudo sensors-detect --auto to load required kernel modules. Test sensor availability with the command sensors.

7. Hybrid Laptop GPUs (NVIDIA Optimus / PRIME) Only Show Integrated GPU

Cause: On power-saving laptops, discrete NVIDIA or AMD GPUs enter a D3 cold power state when idle and power off their PCIe links, making them invisible to standard display server queries.
Fix: Fastfetch can probe discrete GPUs via Vulkan or NVML. On Linux, ensure the NVIDIA proprietary driver and Vulkan ICD loaders are installed. To wake the discrete GPU for a full audit, run:

8. How to Accurately Benchmark Shell Startup Delay

Method: To verify that Fastfetch executes without slowing down your shell, perform an objective benchmark:

Fastfetch typically clocks in between 1.5 ms and 4.2 ms on modern SSD systems. If startup exceeds 50 ms, run fastfetch --show-errors to identify any slow hardware sensors or network calls.