Configuration Guide

xfetch is highly customizable using JSONC (JSON with Comments) files. This guide explains how to customize every aspect of the tool.

Config File Location

By default, xfetch looks for a configuration file at:

Linux: ~/.config/xfetch/config.jsonc
Windows: %APPDATA%\xfetch\config.jsonc
macOS: ~/Library/Application Support/xfetch/config.jsonc

You can also pass a custom config file using the --config flag:

xfetch --config path/to/my_config.jsonc

Curated presets and plugin-oriented examples are maintained separately in xfetch-cli/configs.

Command Line Options

Flag / Command	Description
`xfetch`	Render the fetch with the default (or configured) layout.
`xfetch --config <path>`	Use a custom config file.
`xfetch --daemon`	Run in daemon mode: pin an animated fetch at the top of the terminal while keeping the prompt usable below. See DAEMON.md.
`xfetch --daemon-stop`	Stop the running daemon.
`xfetch --no-daemon-live`	Disable the live stats daemon (`daemon_live`) even if it is enabled in the config.
`xfetch --daemon-live-stop`	Stop the running live stats daemon.
`xfetch --daemon-live-reload`	Force hot reload in the live stats daemon (same as `"daemon_live_reload": true`).
`xfetch --gen-config`	Generate a starter config at the default location. See GEN_CONFIG.md.
`xfetch --clean-cache`	Clear the module cache.
`xfetch --benchmark`	Print benchmarking info for the info gathering step.
`xfetch plugin install\|list\|remove <name>`	Manage plugins. See PLUGINS.md.
`xfetch extension install\|list\|remove <name>`	Manage extensions. See EXTENSIONS.md.
`xfetch theme list\|set\|remove\|export <name>`	Manage themes. See THEMES.md.
`xfetch effects install\|list\|remove <name>`	Manage intro effects. See EFFECTS.md.
`xfetch wasm inspect\|run\|wit`	WebAssembly guest tooling. See WASM.md.
`xfetch update [--check] [--prebuilt] [--bin-dir <dir>] [--yes]`	Check for a newer release and install it when the install method is recognized. See INSTALLATION.md.

Themes

xfetch has a theme system that lets you switch visual styles (colors, icons, layout) independently from your module configuration.

Set the active theme in your config with the theme field:

{
    "theme": "berlin",
    "modules": ["os", "kernel", "memory"]
}

Theme files live in ~/.config/xfetch/themes/<name>.jsonc and contain only visual fields (colors, icons, layout). The theme merges with your config with the theme having highest priority.

See THEMES.md for the full theme system reference.

Basic Structure

A minimal configuration looks like this:

{
    "modules": ["os", "kernel", "memory"],
    "show_colors": true
}

Customizing Modules

The modules array determines which information is displayed and in what order.

Available Modules:

os: Operating System name and architecture
kernel: Kernel version
hostname: Hostname of the machine
user: Current username
uptime: System uptime
datetime: Current date and time
packages: Package count (pacman, dpkg, brew, scoop, etc.). Also packages:<manager> to show a single manager — see Package Count Modules.
shell: Current shell (bash, zsh, powershell, etc.)
terminal: Current terminal emulator
wm: Window Manager / Desktop Environment
cpu: CPU model and frequency
gpu: GPU model
memory: RAM usage
swap: Swap memory usage
disk: Disk usage (first disk)
battery: Battery percentage and status
local_ip: Local IPv4 address
local_ip:v6: Local IPv6 address
public_ip: Public IP address (requires network access)
interfaces: Network interfaces
palette: Color palette

Package Count Modules

The packages module shows the total package count, joining every detected manager on one line:

1090 (pacman) + 21 (aur) + 0 (flatpak)

To show one manager only — as its own module line — use the packages:<manager> key. The manager name must match the label shown between parentheses in the packages output.

{
    // Arch: official packages in one line, AUR packages in another
    "modules": ["os", "kernel", "packages:pacman", "packages:aur"]
}

Per-platform manager labels:

Key	Platform	Counts
`packages`	all	Every detected manager, joined horizontally with `+` .
`packages:pacman`	Arch (pacman)	Official repository packages only (`pacman -Qn`).
`packages:aur`	Arch (pacman)	AUR and manually installed packages (`pacman -Qm`).
`packages:dpkg`	Debian, Ubuntu	apt packages.
`packages:rpm`	Fedora, RHEL, openSUSE	RPM packages.
`packages:apk`	Alpine	Alpine packages.
`packages:xbps-query`	Void	Void packages.
`packages:portage`	Gentoo	Portage packages.
`packages:nix-env`	NixOS	Packages in the user profile (`nix-env -q`).
`packages:flatpak`	Linux	Flatpak applications (when installed).
`packages:snap`	Linux	Snap packages (only when snapd is running).
`packages:brew`	macOS	Homebrew formulae.
`packages:scoop`	Windows	Scoop apps.
`packages:winget`	Windows	Apps installed through the winget source.

Notes:

A manager only appears when it is installed and detected; the same manager can produce several labels (e.g. pacman and aur on Arch).

A packages:<manager> key whose label was not detected renders nothing — the module line is skipped, with no error.

There is no built-in vertical/list rendering of the full breakdown; add one packages:<manager> key per manager to get one line each.

Logos and ASCII Art

You can display custom logos using text files or images.

Color System for ASCII Logos

xfetch supports two methods for coloring ASCII logos:

1. ANSI Escape Codes in Custom ASCII Files

When using a custom ASCII logo file (via logo_path or ascii), you can embed ANSI escape codes directly in the text file to add colors. The escape codes are interpreted by the terminal to render colored text.

Format: \x1b[<code>m or \033[<code>m

Available Foreground Color Codes:

Color	Code	Example
Black	30	`\x1b[30mText\x1b[0m`
Red	31	`\x1b[31mText\x1b[0m`
Green	32	`\x1b[32mText\x1b[0m`
Yellow	33	`\x1b[33mText\x1b[0m`
Blue	34	`\x1b[34mText\x1b[0m`
Magenta	35	`\x1b[35mText\x1b[0m`
Cyan	36	`\x1b[36mText\x1b[0m`
White	37	`\x1b[37mText\x1b[0m`
Gray	90	`\x1b[90mText\x1b[0m`

256-Color Mode: \x1b[38;5;<n>m where <n> is 0-255

RGB True Color: \x1b[38;2;<r>;<g>;<b>m

Reset Code: \x1b[0m (resets all formatting)

Example ASCII Logo with Colors (x_logo.txt):

\x1b[36m      \\\\\\      ///
\x1b[36m       \\\\\\    ///
\x1b[35m        \\\\\\  ///
\x1b[35m         \\\\///
\x1b[33m         ///\\\\
\x1b[33m        ///  \\\\\\
\x1b[32m       ///    \\\\\\
\x1b[32m      ///      \\\\\

This creates a gradient effect from cyan to green.

2. Default ASCII Logo Color

When no custom logo is specified, xfetch uses a built-in default ASCII logo. This logo is rendered with a gray color (RGB: 128, 128, 128) applied programmatically.

The color is set in src/ui/print.rs (DEFAULT_LOGO_COLOR) using crossterm:

SetForegroundColor(Color::Rgb { r: 128, g: 128, b: 128 })

Note: Custom ASCII logos bypass this automatic coloring and use their embedded ANSI codes instead.

Text/ASCII Logos

Create a text file (e.g., logo.txt). You can use ANSI escape codes for colors in this file.

{
    // You can use tilde (~) for home directory
    "logo_path": "~/.config/xfetch/logos/arch.txt",
    // ...
}

ASCII Logo Options

Field	Type	Default	Description
`logo_color`	string	none	Color applied to the ASCII logo. Accepts names (`"Cyan"`), 256-color indexes (`"196"`) and hex RGB (`"#FF0000"`). Also applies to animated logos; lines that already contain ANSI codes are left untouched.
`logo_padding`	number	0	Leading spaces added before the logo (and its frames when animated).
`logo_type`	string	`"auto"`	`"auto"` detects by file extension, `"ascii"` forces text rendering, `"image"` forces image rendering.

{
    "ascii": "~/.config/xfetch/logos/arch.txt",
    "logo_color": "#00FF87",
    "logo_padding": 2
}

Images

xfetch supports displaying images (png, jpg, svg) if your terminal supports it (using protocols like iTerm2, Kitty, or Sixel, handled by viuer).

{
    "logo_path": "/path/to/logo.png",
    // ...
}

Image Logo Options

Field	Type	Default	Description
`logo_width`	number	auto (28% of terminal width, clamped 12-42)	Explicit image width in terminal columns.
`logo_height`	number	auto	Explicit image height in terminal rows.
`logo_gap`	number	12	Gap (in columns) between the logo and the module text.
`logo_kitty`	boolean	`true`	Use the native Kitty graphics protocol when running inside Kitty; set to `false` to fall back to half-block rendering.

Logo Animation (Plugin)

xfetch can animate the ASCII logo via an external plugin. The animation runs only on TTY terminals and only for ASCII logos (not images).

{
    "logo_animation": {
        "plugin": "animate-logo",
        "style": "frame",
        "fps": 6,
        "duration_ms": 8000,
        "loop": true,
        "frames_path": "~/.config/xfetch/logos/fox.txt"
    }
}

Field	Description
`plugin`	Plugin short name or full path to the executable.
`style`	Animation style: `sweep` (default), `wave`, `rainbow`, `sparkle`, `breathing`, `frame`, or `none`.
`fps`	Frames per second (speed of the animation).
`duration_ms`	Total animation duration in milliseconds. Only honored outside daemon mode.
`loop`	Loop the animation (`true`/`false`). Only honored outside daemon mode.
`frames_path`	Frame source for the `frame` style: a single file with frames separated by a line containing `===`, or an array of files (one per frame).

Note: With "daemon": true the animation runs as an infinite loop pinned at the top of the terminal, and duration_ms/loop are ignored. To play a finite animation that stops on its own, leave daemon mode off. See DAEMON.md.

For plugin installation and the protocol details, see PLUGINS.md.

Daemon Mode

Daemon mode pins an animated fetch at the top of the terminal and keeps looping it in the background without blocking the shell prompt.

Field	Type	Default	Description
`daemon`	boolean	`false`	Enable daemon mode. Equivalent to the `--daemon` CLI flag (the CLI flag overrides the config value).
`daemon_min_rows`	number	6	Minimum number of terminal rows left free below the pinned block for command output.

Full reference, usage and troubleshooting: see DAEMON.md.

Live Stats Daemon

daemon_live pins the fetch block at the top of the terminal and re-probes a lightweight module subset every daemon_live_refresh seconds (cpu, memory, battery, datetime, ...), so the pinned fetch stays live. Activation is config-only; disable it from the terminal with --no-daemon-live and stop it with --daemon-live-stop. The animated-logo daemon is unaffected.

Field	Type	Default	Description
`daemon_live`	boolean	`false`	Enable the live stats daemon.
`daemon_live_refresh`	number	per-platform	Seconds between refreshes (Linux 2, macOS 3, Windows 5).
`daemon_live_modules`	array	per-platform	Modules shown/refreshed; defaults to the platform's live set from `platform/<os>/live.rs`.
`daemon_live_reload`	boolean	`false`	Hot reload: watches the config (and active theme) and re-applies changes without restarting. Equivalent CLI flag: `--daemon-live-reload`.

{
    "daemon_live": true,
    "daemon_live_refresh": 2,
    "daemon_live_reload": true,
    "daemon_live_modules": ["cpu", "memory", "battery", "datetime"]
}

Full reference: see the Live Stats Daemon section in DAEMON.md.

Config Providers (Extensions)

Extensions run at config load time and can modify or replace the effective config. They are declared with config_providers:

{
    "config_providers": [
        {
            "extension": "config-roulette",
            "args": {
                "routes": "~/.config/xfetch/routes.json",
                "strategy": "random"
            }
        }
    ]
}

Full reference: see EXTENSIONS.md.

Info Plugins

Plugins can contribute extra module lines. They are declared with info_plugins, each with a plugin name/path and optional args:

{
    "info_plugins": [
        {
            "plugin": "weather",
            "args": { "city": "Madrid" }
        }
    ]
}

Effects (Intro Animations)

Effects animate the way the info appears when xfetch starts. The core renders the module lines, hands them to an effect binary, and plays the returned frames before settling on the final content — e.g. a "decrypt" intro that unscrambles each line.

Effects are opt-in: nothing happens when the effect binary is not installed, and the fetch renders normally. Multiple effects can be chained — they play in sequence.

{
    "effects": [
        { "plugin": "glitch", "duration_ms": 700, "fps": 30 },
        { "plugin": "decrypt", "duration_ms": 1500, "fps": 30 }
    ]
}

Installation: drop the effect binary (xfetch-effect-<name>) in ~/.config/xfetch/effects/ (or anywhere in PATH). Effect implementations are collected in the xfetch-cli/effects repository.

Field	Type	Default	Description
`plugin`	string	—	Effect name (binary `xfetch-effect-<name>`).
`style`	string	none	Effect-specific style selector, passed to the effect.
`duration_ms`	number	effect default	Total animation length in milliseconds.
`fps`	number	effect default	Frames per second.
`args`	object	none	Free-form parameters passed to the effect.
`timeout_secs`	number	30	Safety net: kills the effect process if it runs longer. Unset uses the 30 s default; `0` disables the cap.

The effect protocol lives in xfetch-effect-api (xfetch-cli/api). Effect implementations are collected in xfetch-cli/effects; install them with xfetch effects install <name>. See EFFECTS.md.

Palette Style

The palette module can render in different styles via palette_style:

squares (default)
circles
triangles
lines

{
    "palette_style": "circles"
}

Privacy & Cache

Field	Type	Description
`disable_ip_fetching`	boolean	Skip the network request for the `public_ip` module.
`disable_cache`	boolean	Disable the on-disk cache used for slow probes (e.g. package counts).
`os_wsl_style`	string	WSL OS presentation (Linux only): `off` (plain name), `minimal` (appends `(WSL)`), `full` (appends WSL version and WSLg). Default: `minimal`.

Layouts

Default Layout

The standard "side-by-side" fetch layout.

{
    "layout": null // or omit this field
}

Pac-Man Layout

A boxed layout with a custom header and footer, inspired by Pac-Man.

{
    "layout": "pacman",
    // Icons displayed in the top border
    "header_icons": ["ᗧ", "●", "●", "●"],
    // Text displayed in the bottom border
    "footer_text": "GAME OVER"
}

Icons and Emojis

You can customize the icon displayed next to each module. You can use standard Emojis or Nerd Fonts.

{
    "icons": {
        "os": "",      // Arch Linux icon (Nerd Font)
        "cpu": "󰧑",    // Brain icon (Nerd Font)
        "memory": "RAM:" // Plain text
    }
}

Colors

You can set the color for the icon/label of each module.

Available Colors:

Black
Red
Green
Yellow
Blue
Magenta
Cyan
White
Grey (or Gray)
DarkGrey (or DarkGray)
DarkRed
DarkGreen
DarkYellow
DarkBlue
DarkMagenta
DarkCyan

Color names are case-insensitive. The colors map also accepts 256-color indexes (for example "196") and hex RGB (for example "#FF8800"), the same formats as logo_color. Unrecognized values fall back to white and print a one-time warning.

{
    "colors": {
        "os": "Cyan",
        "cpu": "#FF8800",
        "memory": "196"
    }
}

Keys (Labels)

By default xfetch renders each module as icon value. To display the module label as well, enable show_keys; use key_width to pad the labels to a fixed column count so values align vertically. To rename or hide keys per module and to rewrite values with templates, see SUBMODULES_CONFIGURATION.md.

Field	Type	Default	Description
`show_keys`	boolean	`false`	Render `key: value` in the icon-style layouts (classic, section, compact, custom-x, box variants).
`key_width`	number	auto	Pad the key to this many columns before the `:` separator. Applies wherever keys are shown, including `section` and `minimal`.

{
    "show_keys": true,
    "key_width": 12
}

Renaming Keys: `labels`

The labels map renames the key shown for any module, in every layout (classic and variants, compact, minimal, section, section-box, tree, custom-x). An empty string hides the key — the row shows icon value only. Modules without an entry keep their name.

Field	Type	Default	Description
`labels`	object	`{}`	Per-module key labels: `"cpu": "procesador"` renames the row key; `"cpu": ""` hides it. Colors keep using the raw module key.

{
    "labels": {
        "cpu": "procesador",
        "gpu": ""
    }
}

Value Templates: `formats`

The formats map replaces a module's value with a template. Placeholders {field} are substituted with the module's fields; unknown placeholders render empty, and {{ / }} escape literal braces. Modules without an entry keep their default output.

Module	Fields	Example
every module	`{value}` (current output), `{key}` (module name)	`"os": "Sistema: {value}"`
`cpu`	`{brand}` (raw), `{model}` (cleaned), `{cores}`, `{freq}`	`"cpu": "{model} · {cores} núcleos · {freq}"`
`gpu`	`{name}`, `{vendor}`, `{model}`, `{vram}`	`"gpu": "{vendor} {model}"`

For example, Intel(R) Core(TM) i5-7400 CPU @ 3.00GHz (4) @ 3.00 GHz becomes Intel Core i5-7400 with {model}, and NVIDIA GeForce GTX 1060 6GB becomes NVIDIA GTX 1060 with {vendor} {model}.

{
    "formats": {
        "cpu": "{model} ({cores}) @ {freq}",
        "gpu": "{vendor} {model}"
    }
}

Full Example

{
    "ascii": "~/.config/xfetch/logos/ghost.txt",
    "logo_gap": 8,
    "logo_color": "Cyan",
    "show_keys": true,
    "key_width": 12,
    "theme": "berlin",
    "layout": "pacman",
    "header_icons": ["ᗧ", "ᗣ", "ᗣ"],
    "footer_text": "xfetch",
    "palette_style": "circles",
    "logo_animation": {
        "plugin": "animate-logo",
        "style": "sweep",
        "fps": 12,
        "duration_ms": 1200,
        "loop": false
    },
    "modules": [
        "os",
        "kernel",
        "cpu",
        "memory",
        "palette"
    ],
    "show_colors": true,
    "icons": {
        "os": "",
        "cpu": "",
        "memory": ""
    },
    "colors": {
        "os": "Blue",
        "cpu": "Red",
        "memory": "Yellow"
    }
}

FilesExpand file tree

CONFIGURATION.md

Latest commit

History