Customization

xfetch offers extensive visual customization through logos, icons, colors, and animation effects. All customization is configured in the JSONC configuration file.

Logos

xfetch supports three types of logos: ASCII art, image files, and the built-in default.

Default ASCII Logo

When no custom logo is specified, xfetch displays its built-in ASCII art:


__  __
  \ \/ /
   \  /
   /  \
  /_/\_\
 /____/linux
---------BEGIN PUBLIC KEY----------
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMII
...
----------END PUBLIC KEY-----------

Custom ASCII Logo

To use a custom ASCII logo, set the logo_path or ascii field:

{
    "logo_path": "~/.config/xfetch/logos/arch.txt"
}

ASCII logo files are plain text files. ANSI escape codes can be used for coloring:

\x1b[34m    /\            /\
\x1b[34m   /  \          /  \
\x1b[34m  /\   \        /   /\
\x1b[34m /  \   \      /   /  \
\x1b[34m/   /\   \    /   /\   \
\x1b[34m   /  \   \  /   /  \
\x1b[34m  /    \   \/   /    \
\x1b[34m /______\      /______\
\x1b[0m

Sample logos are included in the xfetch installation at ~/.config/xfetch/logos/:

File	Description
`arch.txt`	Blue ASCII Arch Linux logo (7 lines)
`x_logo.txt`	Cyan-to-green gradient "X" shape (9 lines)
`minimal.txt`	A simple `[ xfetch ]` label (1 line)

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
}

Image Logos

xfetch can render PNG, JPG, and SVG images as logos using the viuer library. This requires terminal support for image display (iTerm2, Kitty, or Sixel-compatible terminals):

{
    "logo_path": "~/.config/xfetch/logos/my-logo.png"
}

Image rendering uses the terminal's native image protocol:

iTerm2: inline image protocol
Kitty: Kitty's native image protocol (high resolution)
Sixel: Sixel graphics (compatible terminals like xterm, mlterm)

If the terminal does not support image display, xfetch falls back to ASCII.

Image Sizing and Positioning

Control image dimensions and spacing with these configuration fields:

{
    "logo_path": "~/.config/xfetch/images/my-image.png",
    "logo_width": 30,
    "logo_height": null,
    "logo_gap": 5
}

Field	Default	Description
`logo_width`	Auto (28% of terminal width, clamped 12–42 cols)	Image width in terminal columns
`logo_height`	Auto (aspect-ratio preserved)	Image height in terminal rows
`logo_gap`	12	Gap in columns between the image and the info text

The auto-width calculation scales with your terminal: wider terminals get proportionally larger images.

ASCII Logo Fields

Field	Default	Description
`logo_color`	none	Color for ASCII logos (name, hex, or RGB)
`logo_colors`	Auto	Per-row colors for ASCII logos (array; row `i` uses `logo_colors[i % len]`)
`logo_padding`	0	Padding around the logo
`logo_type`	Auto	Logo type: `auto`, `ascii`, or `image`

Kitty Terminal Image Rendering

In Kitty terminals, xfetch supports two rendering modes controlled by logo_kitty:

{
    "logo_kitty": true
}

Value	Mode	Description
`true` (default)	Native protocol	Full-resolution images using Kitty's `\x1b_G` graphics protocol. Best quality.
`false`	Half-block	Images rendered using Unicode half-block characters (`▄`). Lower vertical resolution but fully compatible with all terminal features.

Set logo_kitty: false if you experience layout issues with native Kitty rendering (e.g., text overlap or misalignment). The half-block fallback guarantees correct side-by-side layout at the cost of some image fidelity.

Logo Animation

ASCII logos can be animated using the animate-logo plugin. Animation styles transform the logo with color effects over time.

Configuration

{
    "logo_animation": {
        "plugin": "animate-logo",
        "fps": 12,
        "duration_ms": 1200,
        "loop": false,
        "style": "sweep"
    }
}

Animation Styles

Style	Description
`sweep`	Colors sweep left-to-right using a 6-color ANSI palette (red, green, yellow, blue, magenta, cyan)
`wave`	Sine-wave color pattern moves across the logo
`rainbow`	Full RGB gradient shifts over the logo using interpolated 24-bit color
`sparkle`	Random characters briefly light up in bright colors
`breathing`	All characters pulse in warm amber tones (sine-based brightness)
`frame`	Cycles through pre-loaded ASCII frame sets from a frames file
`none`	Static display, no color transformation

Frame-Based Animation

The frame style cycles through pre-defined ASCII frame sets. Frame sets are loaded from a file specified in frames_path:

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

The frames file format uses === as a separator between frame sets:

frame 1 line 1
frame 1 line 2

===

frame 2 line 1
frame 2 line 2

===

frame 3 line 1
frame 3 line 2

Icons

Every module can have a custom icon. Icons are configured in the icons object of the configuration file:

{
    "icons": {
        "os": "\u2302",
        "kernel": "\u2699",
        "hostname": "\u2394",
        "cpu": "\u269b",
        "gpu": "\u26a1",
        "memory": "\u2261",
        "disk": "\u2b23",
        "battery": "\u26a1",
        "uptime": "\u23f1",
        "packages": "\u2b1a",
        "shell": "\u276f",
        "terminal": "\u2b21",
        "wm": "\u25c6",
        "user": "\u263a",
        "datetime": "\u23f0",
        "local_ip": "\u25c9",
        "palette": "\u2588",
        "plugin:<name>": "\u25c8"
    }
}

Icons can be:

Nerd Font glyphs: Unicode characters from the Nerd Fonts patched font set
Unicode symbols: Standard Unicode characters
Text strings: Any short text (e.g., ">>", "+", "OS:")
Empty string: To hide the icon entirely

Default Icons

If not specified in the configuration, xfetch uses built-in default icon mappings for all standard modules.

Colors

Module colors are configured in the colors object:

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

Available Colors

Name	ANSI Code	Description
`Black`	30	Standard black
`Red`	31	Standard red
`Green`	32	Standard green
`Yellow`	33	Standard yellow
`Blue`	34	Standard blue
`Magenta`	35	Standard magenta
`Cyan`	36	Standard cyan
`White`	37	Standard white
`Grey` / `Gray`	90	Bright black

Color Modes

Color output can be disabled entirely:

{
    "show_colors": false
}

Keys

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.

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
}

Example with show_keys and key_width: 12:

cpu       : Apple M4 (10) @ 4.46 GHz
memory    : 10.88 GiB / 16.00 GiB (68%)
disk      : 152.80 GiB / 931.32 GiB (16%) - apfs

Palette Display

The palette module renders an ANSI color swatch. The style is controlled by the palette_style field:

{
    "palette_style": "squares"
}

Palette Styles

Style	Preview
`squares`	Filled background color blocks
`circles`	Colored circle symbols
`triangles`	Colored triangle symbols
`lines`	Thick horizontal color bars

The palette displays 8 colors matching the ANSI standard palette: Black, Red, Green, Yellow, Blue, Magenta, Cyan, White.

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.

{
    "labels": {
        "cpu": "processor",
        "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": "System: {value}"`
`cpu`	`{brand}` (raw), `{model}` (cleaned), `{cores}`, `{freq}`	`"cpu": "{model} · {cores} cores · {freq}"`
`gpu`	`{name}`, `{vendor}`, `{model}`, `{vram}`	`"gpu": "{vendor} {model}"`
`memory`, `swap`	`{used}`, `{total}` (with unit), `{percent}`	`"memory": "{used} / {total} ({percent}%)"`
`disk`	memory fields plus `{fs}`	`"disk": "{used} on {fs}"`
`os`	`{distro}`, `{version}`, `{arch}`, `{wsl}`	`"os": "{distro} {version} ({arch})"`
`packages`	one field per manager (`{pacman}`, `{aur}`, ...), plus `{count}`, `{manager}`, `{managers}`	`"packages": "pkg: {pacman} · aur: {aur}"`
`battery`	`{percent}`, `{state}`	`"battery": "{percent}% [{state}]"`
`uptime`	`{days}`, `{hours}`, `{mins}`	`"uptime": "{days}d {hours}h {mins}m"`
`datetime`	`{date}`, `{time}`	`"datetime": "{date}

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}"
    }
}

Preset Configurations

xfetch ships with numerous preset configurations demonstrating different visual styles.

Showcase Presets (23 examples)

Located in configs/xfetch/presets/showcase/, these presets demonstrate various icon, color, and logo combinations:

Preset	Layout	Key Features
`arch_compact_cyan.jsonc`	classic	Arch logo, all Cyan
`arch_full_blue.jsonc`	classic	Arch logo, all Blue
`green_chevrons_core.jsonc`	classic	`>>` icons, all Green
`minimal_plus_monochrome.jsonc`	classic	Minimal logo, `+` icons, Grey
`minimal_red_compact.jsonc`	classic	Text icons like "OS:", all Red
`monochrome_no_icons.jsonc`	classic	No icons, all White
`neon_hardware_compact.jsonc`	classic	Cyan+Magenta neon theme
`rainbow_letters.jsonc`	classic	R-O-Y-G-B-I-V icons, rainbow colors
`x_logo_full_system.jsonc`	classic	X logo, rainbow coloring
`x_logo_red_hardware.jsonc`	classic	X logo, dot icons, all Red
`pacman_full_white.jsonc`	pacman	X logo, mostly White
`pacman_system_compact.jsonc`	pacman	3 modules, Cyan
`pacman_abc_shell.jsonc`	pacman	A-B-C header
`pacman_minus_uptime.jsonc`	pacman	Minus sign header
`pacman_numeric_hardware.jsonc`	pacman	1-2-3 header
`pacman_plus_os.jsonc`	pacman	Plus sign header
`pacman_question_packages.jsonc`	pacman	Question mark header
`pacman_star_uptime.jsonc`	pacman	Star header
`pacman_symbols_portable.jsonc`	pacman	!-@-# header
`pacman_xox_kernel.jsonc`	pacman	X-O-X header
`pacman_palette_dots.jsonc`	pacman	Dots palette style
`pacman_palette_lines.jsonc`	pacman	Lines palette style
`pacman_palette_triangles.jsonc`	pacman	Triangles palette style

Layout Presets (6 examples)

Located in configs/xfetch/presets/layouts/:

Preset	Layout	Notes
`layout_box_full.jsonc`	box	Full module set with sep separators
`layout_dots_full.jsonc`	dots	Colored module groups
`layout_pacman_full.jsonc`	pacman	Pac-Man icons and "GAME OVER" footer
`layout_section.jsonc`	section	Three groups: Hardware, Software, Session
`layout_side_block.jsonc`	side-block	Text labels as icons
`layout_tree.jsonc`	tree	Nested OS/DE/PC groups

Using Presets

# Run with a specific preset
xfetch --config /path/to/presets/showcase/arch_compact_cyan.jsonc

Or copy a preset to use as your default:

cp configs/xfetch/presets/showcase/neon_hardware_compact.jsonc ~/.config/xfetch/config.jsonc

Navigation Menu

Uh oh!

Customization

Logos

Default ASCII Logo

Custom ASCII Logo

ASCII Logo Options

Image Logos

Image Sizing and Positioning

ASCII Logo Fields

Kitty Terminal Image Rendering

Logo Animation

Configuration

Animation Styles

Frame-Based Animation

Icons

Default Icons

Colors

Available Colors

Color Modes

Keys

Palette Display

Palette Styles

Renaming Keys: `labels`

Value Templates: `formats`

Preset Configurations

Showcase Presets (23 examples)

Layout Presets (6 examples)

Using Presets

Uh oh!

FilesExpand file tree

customization.md

Latest commit

History

customization.md

File metadata and controls

Customization

Logos

Default ASCII Logo

Custom ASCII Logo

ASCII Logo Options

Image Logos

Image Sizing and Positioning

ASCII Logo Fields

Kitty Terminal Image Rendering

Logo Animation

Configuration

Animation Styles

Frame-Based Animation

Icons

Default Icons

Colors

Available Colors

Color Modes

Keys

Palette Display

Palette Styles

Renaming Keys: labels

Value Templates: formats

Preset Configurations

Showcase Presets (23 examples)

Layout Presets (6 examples)

Using Presets

Renaming Keys: `labels`

Value Templates: `formats`