Configuration

xfetch uses a JSONC (JSON with Comments) configuration file. The default location is ~/.config/xfetch/config.jsonc. You can generate a default configuration with xfetch --gen-config or use a custom path with xfetch --config <path>.

Config File Format

JSONC extends standard JSON by allowing C-style (//) and C++-style (/* */) comments and trailing commas in objects and arrays.

Complete Configuration Reference

{
    "layout": "section",
    "modules": [
        {
            "type": "group",
            "title": "Hardware",
            "modules": [
                "hostname",
                "cpu",
                "gpu",
                "memory",
                "swap",
                "disk",
                "battery"
            ]
        },
        {
            "type": "group",
            "title": "Software",
            "modules": [
                "os",
                "kernel",
                "packages",
                "shell",
                "wm",
                "terminal",
                "local_ip"
            ]
        },
        "palette"
    ],
    "show_colors": true,
    "icons": {
        "hostname": "\uf109",
        "cpu": "\uf2db",
        "gpu": "\uf0b9"
    },
    "colors": {
        "hostname": "Green",
        "cpu": "Green",
        "os": "Yellow"
    },
    "palette_style": "squares",
    "logo_path": null,
    "ascii": null,
    "header_icons": null,
    "footer_text": null,
    "disable_ip_fetching": false,
    "disable_cache": false,
    "logo_animation": null,
    "info_plugins": []
}

Field Reference

Top-Level Fields

Field	Type	Default	Description
layout	string or null	null (classic)	Layout style name
modules	array	(see below)	Ordered list of modules or module groups
show_colors	boolean	true	Enable ANSI color output
icons	object	(built-in defaults)	Per-module icon mappings
colors	object	(built-in defaults)	Per-module color mappings
palette_style	string	"squares"	Palette display style
logo_path	string or null	null	Path to a custom logo file
ascii	string or null	null	Path to an ASCII art file (alternative to logo_path)
logo_width	number or null	auto (28% of terminal width, clamped 12-42)	Width constraint for image logos (in terminal columns, auto-calculated if unset)
logo_height	number or null	null	Height constraint for image logos (in terminal rows)
logo_gap	number or null	12	Gap between the logo/image and the info text (in columns)
logo_kitty	boolean or null	true (in Kitty)	Use Kitty native image protocol (true) or half-block rendering (false). Half-block gives lower resolution but avoids layout issues
logo_color	string or null	null	Color applied to the ASCII logo: name ("Cyan"), 256-color index ("196") or hex RGB ("#FF0000")
logo_padding	number or null	0	Leading spaces added before the logo
logo_type	string or null	"auto"	"auto" (by extension), "ascii" (force text), "image" (force image)
show_keys	boolean	false	Render key: value in the icon-style layouts
key_width	number or null	auto	Pad the key to this many columns so values align
labels	object or null	{}	Rename a row key per module; an empty string hides the key
formats	object or null	{}	Value templates with {field} placeholders per module
header_icons	array or null	null	Icons for the top border (Pac-Man layout)
footer_text	string or null	null	Text for the bottom border (Pac-Man layout)
disable_ip_fetching	boolean	false	Disable fetching public IP for privacy
disable_cache	boolean	false	Disable data caching
os_wsl_style	string	"minimal"	WSL OS presentation (Linux only): off (plain name), minimal (appends (WSL)), full (appends WSL version and WSLg)
logo_animation	object or null	null	Logo animation configuration
info_plugins	array	[]	List of info plugins to execute
config_providers	array	[]	List of config provider extensions to run after theme merge
theme	string or null	null	Theme name to apply (visual fields only)
daemon	boolean	false	Run in animated daemon mode (pins the fetch at the top of the terminal)
daemon_min_rows	number	6	Minimum terminal rows required for the animated daemon
daemon_live	boolean	false	Pin a live stats block at the top of the terminal, re-probing modules periodically
daemon_live_refresh	number or null	(per-platform)	Live daemon refresh interval in seconds
daemon_live_modules	array or null	(per-platform)	Modules displayed by the live daemon
daemon_live_reload	boolean	false	Hot-reload the config in live daemon mode
custom_x	object or null	null	Border templates for the custom-x layout
effects	object, array or null	null	Intro effects applied to the content lines

Default Modules

When no modules are specified, xfetch uses:

["os", "kernel", "uptime", "packages", "wm", "shell", "disk", "cpu", "gpu", "memory", "battery"]

Module Groups

Modules can be organized into titled groups for the section and tree layouts:

{
    "type": "group",
    "title": "Hardware",
    "modules": ["cpu", "gpu", "memory"]
}

Groups can be nested:

{
    "type": "group",
    "title": "System",
    "modules": [
        {
            "type": "group",
            "title": "Hardware",
            "modules": ["cpu", "gpu"]
        },
        {
            "type": "group",
            "title": "Software",
            "modules": ["os", "kernel"]
        }
    ]
}

Icons

Icons map module names to display strings. Nerd Font glyphs are commonly used, but any Unicode or text string works.

{
    "icons": {
        "os": "\uf17c",
        "kernel": "\uf17c",
        "hostname": "\uf109",
        "cpu": "\uf2db",
        "gpu": "\uf0b9",
        "memory": "\ue266",
        "swap": "\uf0c5",
        "disk": "\uf0a0",
        "battery": "\uf240",
        "uptime": "\uf253",
        "packages": "\uf187",
        "shell": "\uf0e7",
        "terminal": "\uf0e7",
        "wm": "\uf08e",
        "user": "\uf007",
        "datetime": "\uf017",
        "local_ip": "\uf0ac",
        "palette": "\uf0eb",
        "plugin:<name>": "\uf271"
    }
}

Module keys prefixed with plugin: (e.g., plugin:docker) are used for plugin-provided information.

Colors

Colors map module names to ANSI color names:

{
    "colors": {
        "os": "Cyan",
        "kernel": "White",
        "wm": "Blue",
        "shell": "Green",
        "cpu": "Green",
        "gpu": "Green",
        "memory": "Green",
        "disk": "Green",
        "battery": "Green",
        "packages": "Yellow",
        "hostname": "Green",
        "uptime": "Yellow",
        "terminal": "Green",
        "user": "Magenta"
    }
}

Available color names:

Name	ANSI Code
Black	30
Red	31
Green	32
Yellow	33
Blue	34
Magenta	35
Cyan	36
White	37
Grey or Gray	90

Color names are case-insensitive. 256-color indexes ("196") and hex RGB ("#FF0000") are also accepted.

Palette Styles

The palette module displays a color swatch. Available styles:

Style	Description
"squares"	Background color blocks (default)
"circles"	Foreground color circles
"triangles"	Foreground color triangles
"lines"	Thick horizontal color bars

Animation Configuration

The logo_animation field enables ASCII logo animation via a plugin:

{
    "logo_animation": {
        "plugin": "animate-logo",
        "fps": 12,
        "duration_ms": 1200,
        "loop": false,
        "style": "sweep",
        "frames_path": "~/.config/xfetch/logos/frames.txt"
    }
}

Field	Type	Description
plugin	string	Plugin name (e.g., "animate-logo")
fps	number	Frames per second (1-60)
duration_ms	number	Total animation duration in milliseconds (ignored in daemon mode)
loop	boolean	Whether to loop the animation (ignored in daemon mode)
style	string	Animation style: "sweep", "wave", "rainbow", "sparkle", "breathing", "frame", "none"
frames_path	string	Path to pre-built frame sets (for "frame" style). Multiple frame sets separated by \n===\n
timeout_secs	number	Optional timeout for the animation plugin in seconds

Plugin Integration

Info plugins are configured in the info_plugins array:

{
    "info_plugins": [
        {
            "plugin": "github-stats",
            "args": {
                "username": "myuser",
                "max_lines": 3
            }
        },
        {
            "plugin": "docker"
        }
    ]
}

Field	Type	Description
plugin	string	Plugin name (installed as xfetch-plugin-<name>)
args	object or null	Arbitrary JSON arguments passed to the plugin
timeout_secs	number or null	Optional per-plugin timeout in seconds

Plugin data is accessed via module keys prefixed with plugin::

{
    "modules": ["os", "kernel", "plugin:github-stats", "plugin:docker"]
}

Extension Providers

The config_providers field allows config-level extensions to modify the configuration before rendering. Extensions run after the theme merge, in declaration order:

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

Field	Type	Description
extension	string	Extension name (binary: xfetch-extension-<name>)
args	object or null	Arbitrary JSON arguments passed to the extension
timeout_secs	number or null	Optional per-extension timeout in seconds

Extensions communicate via stdin/stdout JSON, receiving the fully resolved config and returning a modified version. See Extensions for details.

Config File Locations by Platform

Platform	Default Config Path
Linux	~/.config/xfetch/config.jsonc
macOS	~/Library/Application Support/xfetch/config.jsonc
Windows	%APPDATA%\xfetch\config.jsonc