# Fastfetch Documentation - User Manual & Technical Reference

> **Brand:** Fastfetch Documentation & Resource Center  
> **Canonical Web URL:** [https://fastfetch.dev/doc/](https://fastfetch.dev/doc/)  
> **Upstream Repository:** [https://github.com/fastfetch-cli/fastfetch](https://github.com/fastfetch-cli/fastfetch)  
> **Target Version:** 2.68.1  
> **Configuration Format:** JSONC (`config.jsonc`)  
> **Schema Definition:** [Official Fastfetch JSON Schema](https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json)

---

## 1. Quick Start & Execution

Fastfetch can be run with zero configuration or fine-tuned via command-line arguments and configuration dotfiles.

### Essential CLI Flags
```bash
# Execute with default system detection
fastfetch

# Emulate classic Neofetch layout
fastfetch -c neofetch

# Output structured, machine-readable JSON for scripts and AI agents
fastfetch --format json

# Query specific modules only (e.g. CPU, GPU, Memory)
fastfetch -s os:kernel:cpu:gpu:memory --logo none

# Generate a default configuration file
fastfetch --gen-config

# Force overwrite an existing configuration file
fastfetch --gen-config-force

# List all available built-in modules
fastfetch --list-modules

# List all 300+ built-in ASCII distro logos
fastfetch --list-logos

# Display version and compilation feature flags
fastfetch --version
```

---

## 2. Building Fastfetch from Source

Fastfetch is engineered in clean C99/C11. It compiles with CMake and either GCC, Clang, or MSVC.

### A. Linux & BSD Build Instructions
```bash
# 1. Clone the repository recursively
git clone --recursive https://github.com/fastfetch-cli/fastfetch.git
cd fastfetch

# 2. Install core build dependencies
# Debian / Ubuntu:
sudo apt install build-essential cmake pkg-config libvulkan-dev libwayland-dev libx11-dev libxcb-randr0-dev libpci-dev
# Arch Linux:
sudo pacman -S base-devel cmake pkgconf vulkan-headers wayland libxrandr pciutils
# Fedora:
sudo dnf install gcc cmake pkgconf vulkan-loader-devel wayland-devel libXrandr-devel pciutils-devel

# 3. Create build directory and run CMake
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release

# 4. Compile Fastfetch
cmake --build . --target fastfetch -j$(nproc)

# 5. Install system-wide (optional)
sudo cmake --install .
```

### B. macOS Build Instructions
```bash
# Install dependencies via Homebrew
brew install cmake pkg-config

# Clone and compile
git clone --recursive https://github.com/fastfetch-cli/fastfetch.git
cd fastfetch && mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --target fastfetch -j$(sysctl -n hw.ncpu)
```

### C. Windows Native Build (MSYS2 CLANG64)
```bash
# In MSYS2 CLANG64 shell:
pacman -S mingw-w64-clang-x86_64-toolchain mingw-w64-clang-x86_64-cmake
git clone --recursive https://github.com/fastfetch-cli/fastfetch.git
cd fastfetch && mkdir build && cd build
cmake .. -G "Ninja" -DCMAKE_BUILD_TYPE=Release
cmake --build .
```

---

## 3. Display & Logo Engine

Fastfetch features an advanced logo and graphics renderer supporting ASCII art, custom files, and modern terminal image protocols.

### A. Built-In Distro Logos
Fastfetch contains over 300 built-in ASCII distro logos. You can explicitly choose an ASCII logo with:
```bash
fastfetch --logo arch
fastfetch --logo ubuntu
fastfetch --logo debian
fastfetch --logo fedora
fastfetch --logo macos
fastfetch --logo windows
```

### B. Custom Logos & Padding Control
To supply a custom ASCII art file or modify padding:
```bash
# Custom ASCII logo file
fastfetch --logo /path/to/custom_logo.txt

# Modify logo padding (horizontal and vertical margins)
fastfetch --logo-padding 2 --logo-padding-left 1
```

### C. High-Resolution Graphical Image Protocols
Fastfetch natively supports four terminal graphics protocols:
1. **Kitty Graphics Protocol:** High-performance direct GPU blitting on Kitty, WezTerm, Ghostty:
   ```bash
   fastfetch --logo /path/to/image.png --logo-type kitty
   ```
2. **Sixel Graphics Protocol:** Compatible with Foot, WezTerm, XTerm:
   ```bash
   fastfetch --logo /path/to/image.png --logo-type sixel
   ```
3. **iTerm2 Protocol:** Supported on iTerm2 and WezTerm:
   ```bash
   fastfetch --logo /path/to/image.png --logo-type iterm
   ```
4. **Chafa Unicode Half-Blocks (Universal Fallback):** Works in almost every modern terminal emulator (including Windows Terminal, macOS Terminal.app, GNOME Terminal):
   ```bash
   fastfetch --logo /path/to/image.png --logo-type chafa
   ```

---

## 4. Configuration & Dotfile Management

Fastfetch configuration files are written in **JSONC** (JSON with comments).

### Configuration File Locations
Fastfetch searches for configuration files in this priority order:
1. File explicitly passed via `--config <path>` or `-c <preset>`
2. `%USERPROFILE%\.config\fastfetch\config.jsonc` (Windows) or `~/.config/fastfetch/config.jsonc` (Linux/macOS)
3. System-wide configuration at `/etc/fastfetch/config.jsonc`

### JSON Schema Integration
Add the `$schema` directive at the top of your `config.jsonc` to activate live autocompletion and module validation in editors:
```jsonc
{
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json",
  "logo": {
    "type": "auto"
  },
  "display": {
    "separator": ": ",
    "color": {
      "keys": "blue"
    }
  },
  "modules": [
    "title",
    "separator",
    "os",
    "host",
    "kernel",
    "uptime",
    "packages",
    "shell",
    "display",
    "cpu",
    "gpu",
    "memory",
    "disk",
    "break",
    "colors"
  ]
}
```

---

## 5. Format String Guide & Text Manipulation

Fastfetch enables granular control over module output formatting using format strings. Always use named format arguments instead of deprecated numeric indices.

### A. Formatting Capabilities & Modifiers
| Syntax Pattern | Operation | Output Example |
| :--- | :--- | :--- |
| `{name:5}` | Truncate to first 5 characters | `"Intel Core..."` &rarr; `"Intel"` |
| `{name:-5}` | Truncate with ellipsis (`…`) | `"Intel Core..."` &rarr; `"Intel…"` |
| `{name<15}` | Left-align and pad right with spaces to 15 chars | `"Arch Linux    "` |
| `{name>15}` | Right-align and pad left with spaces to 15 chars | `"    Arch Linux"` |
| `{name\|15}` | Center-align with space padding to 15 chars | `"  Arch Linux  "` |
| `{name~0,4}` | Substring slice: start at index 0, length 4 | Extracts first 4 characters |
| `{?user}User: {user}{?}{/user}Guest{/}` | Conditional fallback if variable is unset | Fallback text |

### B. Color Codes, Variables & Constants
- **Color Placeholders:** `{#1}` through `{#9}` bind dynamically to your terminal palette colors.
- **Reset Terminator:** `{-}` ends the active styling.
- **Environment Variables:** Reference variables with `{$USER}`, `{$HOSTNAME}`, `{$XDG_CURRENT_DESKTOP}`.
- **Custom Constants:** Declare constants in `"display": { "constants": ["ServerAlpha"] }` and reference with `{$1}`.

---

## 6. Complete 75+ Module Reference Catalog

Fastfetch provides over 75 modular telemetry collectors. Below is the organized module reference:

### 1. System & OS Modules
- `title`: Username, hostname, and separator bar (`user@host`).
- `os`: Operating system name, distribution version, codename, architecture, and variant.
- `host`: Hardware model name, chassis type, motherboard vendor, and revision.
- `kernel`: Kernel release version, build date, and architecture.
- `uptime`: System uptime formatted in days, hours, and minutes.
- `packages`: Total package counts detected across pacman, dpkg, rpm, flatpak, snap, brew, nix, etc.
- `shell`: Shell name, version, and binary path (bash, zsh, fish, pwsh, nu).
- `de`: Desktop Environment name and version (GNOME, KDE Plasma, XFCE, Hyprland, Sway).
- `wm`: Window manager name and compositing protocol (Wayland or X11).
- `wmtheme`: Window manager theme name.
- `theme`: GTK / Qt / system visual appearance theme.
- `icons`: Active system icon theme.
- `font`: Desktop and interface font configuration.
- `cursor`: Active mouse cursor theme and size.
- `terminal`: Active terminal emulator application (Kitty, Alacritty, WezTerm, Windows Terminal).
- `terminalfont`: Font family and size configured in the terminal emulator.
- `terminalsize`: Current terminal window columns and rows.
- `terminaltheme`: Terminal color palette theme.

### 2. Hardware & Processor Modules
- `cpu`: Processor brand, model, physical & logical core count, base/boost frequency, and temperature.
- `cpuusage`: Real-time overall CPU utilization percentage.
- `gpu`: Discrete and integrated GPU model, driver version, core clock, temperature, and VRAM.
- `memory`: Total, used, and available system RAM, percentage bar, and threshold alerts.
- `swap`: Total and allocated swap space.
- `disk`: Mounted disk partitions, filesystem type, total, free, and used capacity.
- `btrfs`: Dedicated Btrfs filesystem subvolume statistics.
- `zpool`: ZFS storage pool health, fragmentation, and capacity.
- `battery`: Internal battery capacity percentage, status (charging/discharging), cycle count, and health.
- `poweradapter`: AC power supply wattage, manufacturer, and connection status.
- `lm`: Lightdm/GDM/SDDM login display manager status.

### 3. Peripherals & Displays
- `display`: Connected monitor resolution, refresh rate (Hz), DPI scaling, HDR status, and bit depth.
- `brightness`: Current monitor panel backlight brightness level.
- `sound`: Audio output hardware, default sink, volume percentage, and active sound server (PipeWire, PulseAudio, ALSA).
- `camera`: Connected USB or internal webcams and sensors.
- `gamepad`: Connected game controllers and joysticks.
- `bluetooth`: Paired Bluetooth devices, battery percentages, and connection state.

### 4. Network & Connectivity Modules
- `localip`: Local network IPv4/IPv6 interface addresses.
- `publicip`: Public external IPv4/IPv6 address (optional network query).
- `wifi`: Active Wi-Fi SSID, protocol standard (802.11ax/ac/n), signal strength, and PHY rate.
- `dns`: Configured upstream DNS resolver addresses.
- `netio`: Total network bytes received and transmitted across network interfaces.

### 5. Media & Process Modules
- `player`: Currently active MPRIS / media player application.
- `media`: Current playback track title, artist name, and album.
- `processes`: Total number of running processes and threads.
- `users`: Logged-in user accounts and sessions.
- `break`: Blank line spacer for layout alignment.
- `colors`: Terminal 16-color ANSI palette test blocks.

---

## 7. Neofetch to Fastfetch Migration Reference

| Neofetch Directive | Fastfetch Equivalent | Function |
| :--- | :--- | :--- |
| `neofetch` | `fastfetch -c neofetch` | Standard Neofetch emulation |
| `neofetch --off` | `fastfetch --logo none` | Disable ASCII logo |
| `neofetch --stdout` | `fastfetch --pipe false` | Clean plain text output |
| `neofetch --config /path` | `fastfetch -c /path` | Custom configuration file |
| `neofetch --ascii_distro name` | `fastfetch --logo name` | Set ASCII logo distribution |
| `neofetch --image /path` | `fastfetch --logo /path` | Render graphic image logo |
| `neofetch --cpu_temp C` | `{"type": "cpu", "temp": true}` | Enable CPU temperature display |
| `neofetch --memory_percent on` | `{"type": "memory", "percent": {"type": 3}}` | Enable percentage display |

---

## 8. Troubleshooting Knowledgebase & Known Issues

### 1. Windows 2–3s Cold-Start Latency
- **Root Cause:** Windows DCOM / WMI subsystem cold-start delays on initial process invocation.
- **Solution:** In `config.jsonc`, add `"general": { "processingTimeout": 500 }` to avoid waiting indefinitely for unresponsive WMI queries. On desktop PCs without a battery, remove the `"battery"` module to eliminate slow ACPI power queries.

### 2. Missing Nerd Font Glyphs & Square Boxes
- **Root Cause:** Terminal emulator font does not bundle Powerline or Nerd Font symbols.
- **Solution:**
  - **Arch Linux:** `sudo pacman -S ttf-jetbrains-mono-nerd`
  - **macOS:** `brew install font-jetbrains-mono-nerd-font`
  - **Windows:** Install Cascadia Code with Nerd Fonts (`winget install Microsoft.CascadiaCode`) or JetBrains Mono Nerd Font, then set it in Windows Terminal settings.

### 3. High-Resolution Images Not Displaying
- **Root Cause:** Selected image protocol is unsupported by the current terminal emulator.
- **Solution:** Test terminal protocol capability:
  - Kitty protocol works in Kitty, WezTerm, and Ghostty.
  - Sixel works in Foot and WezTerm.
  - For universal cross-terminal compatibility on Windows Terminal and macOS Terminal.app, use Chafa Unicode half-blocks:
    ```bash
    fastfetch --logo /path/to/image.png --logo-type chafa
    ```

### 4. Remote SSH Login (SCP / SFTP) Broken by `~/.bashrc`
- **Root Cause:** Unconditional output printed during non-interactive SSH connections corrupts the binary packet stream of `scp`, `sftp`, and automated Git operations.
- **Solution:** Wrap the call in an interactive shell guard:
  ```bash
  if [[ $- == *i* ]]; then
      fastfetch
  fi
  ```

### 5. Missing or Inaccurate Package Counts
- **Root Cause:** Locked package manager databases (e.g. `/var/lib/pacman/db.lck`), unexported Homebrew environment variables, or sandboxed flatpak permissions.
- **Solution:**
  - Ensure Homebrew is in shell PATH: `eval "$(/opt/homebrew/bin/brew shellenv)"`.
  - For Flatpak permissions, ensure read access to `/var/lib/flatpak` and `~/.local/share/flatpak`.

### 6. Missing CPU / GPU Temperatures on Linux
- **Root Cause:** Hardware monitoring kernel modules (e.g. `coretemp`, `k10temp`, `nct6775`) are not loaded.
- **Solution:** Install `lm_sensors` and run `sudo sensors-detect --auto`. Verify sensors with `sensors`.

### 7. Hybrid / Dual-GPU Laptop Detection
- **Root Cause:** Discrete NVIDIA GPU is in ultra-low-power PCIe D3 state when idle.
- **Solution:** On Linux laptops with NVIDIA PRIME, run:
  ```bash
  __NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia fastfetch
  ```

### 8. How to Accurately Benchmark Shell Startup Delay
- **Diagnostic Method:** Measure actual sub-millisecond execution time:
  ```bash
  hyperfine 'fastfetch --pipe false'
  ```
  Fastfetch typically executes between **1.5 ms and 4.2 ms**. If execution exceeds 50 ms, run `fastfetch --show-errors` to identify slow hardware sensors.

---

## Documentation Links & Trust Anchors

- **Documentation Home:** [https://fastfetch.dev/doc/](https://fastfetch.dev/doc/)
- **Landing Page:** [https://fastfetch.dev/](https://fastfetch.dev/) (Markdown: [index.md](https://fastfetch.dev/index.md))
- **About the Project:** [https://fastfetch.dev/about](https://fastfetch.dev/about) (Markdown: [about.md](https://fastfetch.dev/about.md))
- **Contact & Support:** [https://fastfetch.dev/contact](https://fastfetch.dev/contact) (Markdown: [contact.md](https://fastfetch.dev/contact.md))
- **Privacy Policy:** [https://fastfetch.dev/privacy](https://fastfetch.dev/privacy) (Markdown: [privacy.md](https://fastfetch.dev/privacy.md))
- **AI Agent Integration Guide:** [https://fastfetch.dev/AGENTS.md](https://fastfetch.dev/AGENTS.md)
- **Machine-Readable LLM Index:** [https://fastfetch.dev/llms.txt](https://fastfetch.dev/llms.txt)
- **XML Sitemap:** [https://fastfetch.dev/sitemap.xml](https://fastfetch.dev/sitemap.xml)