A highly customizable system information fetch tool written in Rust. Display system information with style, featuring Kitty image protocol support, custom scripts, multiple display modes, and extensive configuration options.
  • Rust 94.2%
  • Roff 3.4%
  • Nix 1.4%
  • Ruby 0.5%
  • Shell 0.5%
Find a file
Matthew Weber e0202e6cfe
Some checks failed
CI / check (push) Has been cancelled
fix(nix): read the generation from the system profile link
nh os info computes closure sizes and now outlasts the 3 s command
timeout, so the fetch fell through to the user-profile count ("3 user
generations") and cached it. The current generation is in the
/nix/var/nix/profiles/system symlink target, so read that first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 03:07:02 -05:00
.forgejo/workflows fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
assets chore(assets): shrink oversized Bluefin artwork by 79% 2026-08-10 13:22:10 -04:00
Formula fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
src fix(nix): read the generation from the system profile link 2026-11-19 03:07:02 -05:00
.envrc fix ascii logos and add in boottime and package count features. 2026-02-23 02:09:49 -05:00
.gitignore fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
ARCH_PACKAGING.md new logo logic 2025-10-25 16:23:40 -04:00
Cargo.lock fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
Cargo.toml fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
CHANGELOG.md fix(nix): read the generation from the system profile link 2026-11-19 03:07:02 -05:00
config.example.toml feat(now-playing): read MPRIS over D-Bus so playerctl is optional 2026-08-10 21:40:57 -04:00
default.nix fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
flake.lock flake.lock 2026-01-03 21:01:17 -05:00
flake.nix fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
LICENSE new logo logic 2025-10-25 16:23:40 -04:00
mattfetch.1 fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
PKGBUILD release: 0.7.0 2026-08-10 19:59:38 -04:00
PKGBUILD-git release: 0.7.0 2026-08-10 19:59:38 -04:00
PKGBUILD-local release: 0.7.0 2026-08-10 19:59:38 -04:00
README.md fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
rustfmt.toml fix: address full review (timeouts, distro detection, image fallbacks, packaging) 2026-11-15 17:04:42 -05:00
screenshot.png add screenshot 2025-10-25 02:11:04 -04:00

mattfetch

A highly customizable system information fetch tool written in Rust. Display system information with style, featuring Kitty image protocol support, custom scripts, multiple display modes, and extensive configuration options.

screenshot

Table of Contents

Features

  • Kitty Image Protocol Support

    • Display beautiful images instead of ASCII art in kitty and Ghostty
    • Automatic detection of terminal type (images are never sent when output is piped or redirected)
    • Proper text alignment alongside images
    • Configurable image paths
    • Anime mode - use custom anime/artwork images instead of distro logos
      • Built-in anime images that cycle sequentially through available images
      • Add as many images as you want (anime.png, anime2.png, anime3.png, ...)
      • Auto-detects all available images (supports gaps in numbering)
      • Choose specific built-in anime or use your own custom image
    • Multiple logo positions: left, top, or right
    • Adjustable logo size (in pixels)
  • Multi-Color ASCII Art Fallback

    • Beautiful multi-color ASCII logos for other terminals
    • Automatic distro detection with matching logo, from /etc/os-release's ID and ID_LIKE as well as its name, so a derivative without its own logo (Garuda, KDE neon) shows its base distro's. A distro with no match gets the generic Tux.
    • Supports 15+ distributions: NixOS, Arch, Ubuntu, Debian, Fedora, openSUSE, EndeavourOS, Manjaro, Gentoo, Void, Pop!_OS, Linux Mint, CachyOS, Bluefin, and generic Linux
    • ASCII art sourced from fastfetch with proper color schemes
  • Comprehensive System Information

    • Hostname and username
    • System uptime
    • Distribution and kernel version
    • Desktop Environment and Window Manager detection
    • CPU and GPU information (with smart GPU model extraction)
    • Memory and disk usage
    • System creation date/age
    • NixOS generations count (via nh os info)
    • Current shell
    • Package counts (auto-detects: nix, pacman, apt/dpkg, rpm, zypper, flatpak, snap, brew)
  • Theme Detection

    • Reads from ~/.config/current.theme (set by hyprchanger.sh)
    • Hyprland config parsing
    • Waybar theme detection
    • GTK theme fallback
  • Custom Scripts

    • Execute and display output from your own scripts
    • Easy to add via configuration file
    • Toggle individual scripts on/off
    • Integration with fastfetch scripts
    • Per-script color customization for labels and values
  • Challenge Tracker

    • Track progress on multiple time-based challenges simultaneously
    • Display days completed, days remaining, and percentage
    • Optional challenge title with icon and underline
    • Gamification system — rank tiers, XP points, and RPG-style levels
    • Achievement badge row — tier icons displayed directly under the logo/ASCII art
    • File-based trackers for monitoring last update/backup dates
    • Fully configurable with custom icons and colors
  • Display Modes

    • Normal mode with Kitty images or ASCII art fallback
    • Compact mode for minimal output
    • Section breaks for better readability
    • Per-label color customization
    • Optional border around output (when not using images)
  • Nerd Font Icons (Optional)

    • Beautiful icons for each system info field
    • Custom icons for custom scripts
    • Can be disabled globally or per-run
    • Graceful fallback if nerd fonts not installed
  • Fully Configurable

    • TOML configuration file
    • Toggle any information module
    • Customize colors and separators
    • Custom label colors per field
    • Configurable section breaks
    • Add unlimited custom scripts

Installation

Prerequisites

mattfetch is written in Rust, so you'll need to have Rust installed to build from source.

Required: Installing Rust

If you don't have Rust installed, install it using rustup:

# Install Rust using rustup (recommended)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Follow the on-screen instructions, then reload your shell
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

For more information, visit https://rustup.rs/

Optional: Installing Nerd Fonts

For the best experience with icons, install a Nerd Font. Nerd Fonts are not required - mattfetch works fine without them, but they enhance the visual output with beautiful icons.

Popular Nerd Fonts:

  • JetBrainsMono Nerd Font
  • FiraCode Nerd Font
  • Hack Nerd Font
  • Meslo Nerd Font

Installation:

# On Arch/Manjaro
sudo pacman -S ttf-jetbrains-mono-nerd

# On NixOS (add to configuration.nix)
fonts.packages = with pkgs; [
  (nerdfonts.override { fonts = [ "JetBrainsMono" "FiraCode" ]; })
];

# Manual installation
# Download from https://www.nerdfonts.com/
# Extract and move to ~/.local/share/fonts/
# Run: fc-cache -fv

After installing, configure your terminal to use a Nerd Font. If you don't have Nerd Fonts installed, you can disable icons with show_icons = false in the config or use the --no-icons flag.

From Source

# Clone the repository
git clone <repository-url>
cd mattfetch

# Build with cargo
cargo build --release

# The binary will be available at target/release/mattfetch
# You can run it directly:
./target/release/mattfetch

# Or install it to your system (installs to ~/.cargo/bin)
cargo install --path .

# Optionally, install the man page manually:
sudo install -Dm644 mattfetch.1 /usr/share/man/man1/mattfetch.1
# Or for user-local install:
mkdir -p ~/.local/share/man/man1
install -Dm644 mattfetch.1 ~/.local/share/man/man1/mattfetch.1

Note: Make sure ~/.cargo/bin is in your PATH to run installed binaries. The man page and assets folder are not automatically installed with cargo install.

Using Nix

mattfetch can be installed using Nix with both flakes and traditional Nix.

Build and run directly from the repository:

# Build the package
nix build

# Run it directly
nix run

# Test the built binary
./result/bin/mattfetch

Install to your user profile:

nix profile install .

Add to your NixOS configuration:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    mattfetch.url = "git+https://codeberg.org/thelinuxcast/mattfetch.git";
  };

  outputs = { self, nixpkgs, mattfetch, ... }: {
    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
      # ... your config
      modules = [
        {
          environment.systemPackages = [
            mattfetch.packages.x86_64-linux.default
          ];
        }
      ];
    };
  };
}

Add to home-manager:

{
  inputs = {
    home-manager.url = "github:nix-community/home-manager";
    mattfetch.url = "git+https://codeberg.org/thelinuxcast/mattfetch.git";
  };

  outputs = { self, nixpkgs, home-manager, mattfetch, ... }: {
    homeConfigurations.yourusername = home-manager.lib.homeManagerConfiguration {
      # ... your config
      modules = [
        {
          home.packages = [
            mattfetch.packages.x86_64-linux.default
          ];
        }
      ];
    };
  };
}

Development shell:

# Enter development environment with Rust toolchain
nix develop

Without Flakes

Build the package:

nix-build
./result/bin/mattfetch

Install to your user profile:

nix-env -f default.nix -i

Add to your NixOS configuration:

# In configuration.nix or a separate module
{ pkgs, ... }:

let
  mattfetch = pkgs.callPackage /path/to/mattfetch/default.nix { };
in
{
  environment.systemPackages = [ mattfetch ];
}

Homebrew

mattfetch can be installed on Linux via Homebrew using the formula in this repository. It is Linux-only: it reads /proc, /etc/os-release and other Linux sources, so the formula declares depends_on :linux.

From the Formula File

From a local checkout:

brew install ./Formula/mattfetch.rb

Adding as a Tap

For easier updates, clone the repository into a tap. The clone URL is required because the tap is not hosted on GitHub:

brew tap thelinuxcast/mattfetch https://codeberg.org/thelinuxcast/mattfetch.git
brew trust --formula thelinuxcast/mattfetch/mattfetch  # required since Homebrew 6.0
brew install mattfetch

To build the latest commit from main instead of the stable release:

brew install --HEAD mattfetch

Note: Homebrew installs the binary, the mattfetch.1 man page, and the assets folder into the Cellar automatically.

Arch Linux

mattfetch can be built and installed as an Arch Linux package.

From AUR (Once Published)

Using an AUR helper like yay or paru:

# Install stable version
yay -S mattfetch

# Or install git version (latest development)
yay -S mattfetch-git

Or manually:

git clone https://aur.archlinux.org/mattfetch.git
cd mattfetch
makepkg -si

Build Locally

For testing or local installation:

# Build from the local directory
makepkg -p PKGBUILD-local -si

# Or build from git
makepkg -p PKGBUILD-git -si

For detailed instructions on building and publishing to the AUR, see ARCH_PACKAGING.md.

Usage

Basic Usage

Simply run:

mattfetch

Getting Help

View the comprehensive man page:

man mattfetch

The man page includes detailed information about all options, configuration settings, and examples.

Command Line Options

# Use compact mode
mattfetch --compact
mattfetch -c

# Change logo position (overrides config)
mattfetch --logo-position top
mattfetch -p right

# Disable logo display
mattfetch --no-logo
mattfetch -n

# Display only custom scripts (hides all system info)
mattfetch --custom-scripts-only
mattfetch -s

# Show the terminal's 16 ANSI colors
mattfetch --colors

# Show the currently playing track
mattfetch --now-playing

# Combine options
mattfetch --logo-position top --compact
mattfetch -p right -c

# Show configuration file path
mattfetch config-path

# Edit configuration file
mattfetch edit-config

# Generate default configuration (refuses to replace an existing file)
mattfetch generate-config

# Replace an existing configuration with the defaults
mattfetch generate-config --force

Available Command Line Flags

Flag Short Description
--compact -c Use compact single-line mode
--config <PATH> -f Use custom config file path
--logo-position <POS> -p Set logo position: left, right, or top (overrides config)
--no-logo -n Disable logo display
--anime -a Enable anime mode (use anime image instead of distro logo)
--custom-scripts-only -s Display only custom scripts (hides system info, logo, challenges, trackers, Now Playing and colors)
--no-icons Disable nerd font icons
--colors Show the terminal's 16 ANSI colors as a row of blocks
--now-playing Show the currently playing track (needs playerctl or mpc)
--test-logos Render every bundled logo in turn
--custom-distro <NAME> Override the detected distro (for testing)
--version -v Print version
--help -h Print help information

Configuration

Configuration file is automatically created at ~/.config/mattfetch/config.toml on first run.

Keys mattfetch does not recognise are reported on stderr (Warning: unknown config key 'display.logo_sise' ...) rather than silently ignored, so a misspelt key is noticed instead of quietly doing nothing.

Example Configuration

# Display mode: compact or normal
compact = false

# How long any external command (a module's tool or a custom script) may run, in
# milliseconds, before it is killed and its line left out. Default 3000.
command_timeout_ms = 3000

# Configure which information modules to display
[modules]
hostname = true
username = true
uptime = true
distro = true
kernel = true
desktop = true
window_manager = true
theme = true
cpu = true
gpu = true
memory = true
disk = true
system_age = true
nix_generations = true
shell = true
packages = true

# Configure the display appearance
[display]
separator = ": "
label_color = "cyan"
value_color = "white"
show_logo = true
show_icons = true    # Enable nerd font icons (requires nerd font installed)
color_icons = true   # Icons match label colors (default: true)

# Logo override (for Kitty terminal). Omit to pick the logo from the detected
# distro. Accepts a bundled asset name or a path to your own image.
image_path = "bluefin-3"                      # a bundled asset (".png" optional)
# image_path = "/home/user/Pictures/nixos.png"  # or any file of your own

# Anime mode - use anime/custom artwork instead of distro logos
anime_mode = false  # Set to true to enable
anime_image_path = "/home/user/Pictures/anime.png"  # Optional: custom anime image
anime_builtin = 3  # Optional: choose specific built-in anime (1-N), cycles if not set
anime_size = 400  # Optional: custom size in pixels, uses logo_size if not set

# Logo position: left, top, or right (default: left)
logo_position = "left"

# Logo size in pixels (width - height maintains aspect ratio)
logo_size = 300

# Section breaks - add blank lines after these labels
section_breaks = ["Shell", "Theme"]

# Custom label colors - override default for specific fields
[display.label_colors]
CPU = "yellow"
GPU = "yellow"
Memory = "green"
Disk = "green"

# Custom scripts
[[custom_scripts]]
name = "Weather"
command = "curl -s 'wttr.in/?format=3'"
enabled = true
label_color = "blue"     # Optional: custom colors for this script
value_color = "cyan"
icon = ""              # Optional: custom nerd font icon

[[custom_scripts]]
name = "Package Count"
command = "nix-env -qa --installed | wc -l"
enabled = true
icon = "󰏖"              # Optional: custom nerd font icon

Available Colors

  • cyan
  • red
  • green
  • yellow
  • blue
  • magenta
  • white
  • black

Nerd Font Icons

mattfetch supports nerd font icons for a more visually appealing output. Icons are optional and enabled by default if you have a nerd font installed.

Built-in Icons:

Each system information field has a pre-configured icon:

  • OS icon (automatically detects your distro):
    • 󱄅 NixOS
    • 󰣇 Arch Linux
    • Ubuntu
    • Debian
    • Fedora
    • openSUSE
    • Generic Linux (fallback)
  • Kernel (Linux Tux)
  • 󰔟 Uptime
  • Shell
  • Desktop Environment
  • Window Manager
  • 󰏘 Theme
  • 󰻠 CPU
  • 󰍹 GPU
  • 󰑭 Memory
  • 󰋊 Disk
  • 󱫐 System Age
  • 󱄅 NixOS Generations
  • 󰏖 Packages

Icon Colors:

By default, icons inherit the same color as their labels. You can disable this to keep icons in their default color:

[display]
show_icons = true
color_icons = true   # Icons match label colors (default: true)

When color_icons = false, icons remain uncolored while labels still use custom colors.

Disabling Icons:

If you don't have nerd fonts installed or prefer not to use icons:

[display]
show_icons = false  # Disable icons globally

Or disable them temporarily with the CLI flag:

mattfetch --no-icons

Custom Icons for Scripts:

You can add custom nerd font icons to your custom scripts:

[[custom_scripts]]
name = "Weather"
command = "curl -s 'wttr.in/?format=3'"
enabled = true
icon = ""  # Weather icon

[[custom_scripts]]
name = "Git Repos"
command = "ls ~/git | wc -l"
enabled = true
icon = ""  # Git icon

To find nerd font icons, visit https://www.nerdfonts.com/cheat-sheet

Adding Custom Scripts

Add any number of custom scripts to display additional information:

[[custom_scripts]]
name = "My Custom Info"
command = "echo 'Hello from my script!'"
enabled = true

[[custom_scripts]]
name = "Git Status"
command = "git status --short 2>/dev/null | wc -l"
enabled = true

[[custom_scripts]]
name = "Days on Current Theme"
command = "bash /home/user/.local/bin/theme.sh"
enabled = true
label_color = "magenta"   # Optional: custom label color
value_color = "yellow"    # Optional: custom value color
icon = "󰏘"                # Optional: custom nerd font icon

Each script can optionally specify its own label_color, value_color, and icon. If not specified, it will use the default colors from [display] and no icon.

Multi-line output is joined onto one line, since the display is line-oriented.

Scripts run concurrently, and each is killed if it runs past command_timeout_ms (default 3 seconds), so one slow or hung script cannot stall the whole fetch.

A config file is executable content. Enabled command values run through sh -c on every invocation, so a config is as trusted as a shell script. Treat one you did not write — including anything passed via --config — the same way you would treat running that script yourself.

Challenge Tracker

Track progress on time-based challenges (like a 75 Hard challenge, 100-day coding streak, or any custom goal). You can track multiple challenges simultaneously:

[[challenges]]
enabled = true
title = "My 730 Day Challenge"
title_icon = "🎯"           # Optional: icon before the title
title_underline = true      # Optional: add underline below title (default: true)
show_progress_bar = true    # Optional: show mini progress bar below title (default: true)
start_date = "7/9/2025 01:27AM"    # Or use ISO format: "2025-07-09T01:27:00"
end_date = "7/10/2027 01:27AM"
show_days_done = true
show_days_left = true
show_percentage = true      # Show percentage in days_done output
days_done_icon = "\U000F00EE"  # Nerd font icon for days done (use \UXXXXXXXX notation)
days_left_icon = "󰃭"           # Nerd font icon for days left
label_color = "magenta"     # Optional: custom color for all challenge labels

# Gamification
show_rank = true            # Show tier rank (Seedling → Mythical)
show_xp = true              # Show XP earned
show_level = true           # Show level alongside XP
xp_per_day = 10             # XP awarded per completed day
rank_display_icon = "󰖅"    # Icon for the Rank label
xp_display_icon = "󰓥"      # Icon for the XP label

[[challenges]]
enabled = true
title = "100 Days of Code"
title_icon = "💻"
show_progress_bar = true
start_date = "2026-01-01"
end_date = "2026-04-11"
show_days_done = true
show_days_left = true

Date Format Options:

  • "7/9/2025 01:27AM" - US format with 12-hour time
  • "2025-07-09T01:27:00" - ISO 8601 format
  • "2025-07-09" - Date only (midnight assumed)

Output Example:

🎯 My 730 Day Challenge
───────────────────────
[█████──────────────────]
 Days Done: 177 days done - 24%
󰃭 Days Left: 553 days left
󰖅 Rank: Bronze
󰓥 XP: 1770 pts  ·  Lv. 5

💻 100 Days of Code
───────────────────
[█───────────────]
 Days Done: 4 days done - 4%
󰃭 Days Left: 96 days left

Progress Bar Features:

  • Automatically matches the exact length of the challenge title
  • Uses colored filled blocks (█) matching the challenge's label color
  • Can be disabled per-challenge by setting show_progress_bar = false

Challenge Gamification

Each challenge can optionally display a rank tier, XP points, and RPG-style level based on your progress percentage.

Rank Tiers (based on % complete):

Tier Threshold Color
Seedling 0–9% Green
Copper 10–24% Amber
Iron 25–39% Grey
Bronze 40–54% Brown
Silver 55–64% Silver
Gold 65–74% Yellow
Platinum 75–84% Steel blue
Emerald 85–89% Emerald green
Diamond 90–99% Ice blue
Mythical 100% Magenta

XP & Leveling:

  • XP = days_done × xp_per_day (default 10 XP/day)
  • Level uses a sqrt curve: fast early levels that slow down over time
    • Lv. 1 at 0 XP, Lv. 2 at ~100 XP, Lv. 3 at ~400 XP, Lv. 4 at ~900 XP, ...

Configuration:

[[challenges]]
# ...
show_rank = true       # Show tier rank badge (default: true)
show_xp = true         # Show XP total (default: true)
show_level = true      # Show level alongside XP (default: true)
xp_per_day = 10        # XP per completed day (default: 10)
rank_display_icon = "󰖅"
xp_display_icon = "󰓥"

Achievement Badges

For the first enabled challenge, an achievement badge row is displayed directly beneath the logo or ASCII art column, centred on it. Each tier you have reached shows its colored icon — the current tier is bold.

The badge row appears automatically when show_rank = true on the first enabled challenge. It only shows in left logo position and ASCII art mode (not in top or right positions where the layout doesn't support a separate left column).

Rank, XP and the badge row describe overall progress, so they come from the first enabled challenge only. Additional enabled challenges still show their own title, progress bar and day counts — they just don't each get a competing rank.

Badge Size

[display]
badge_scale = 2   # 1-7, default 2

Badges are scaled with kitty's text sizing protocol, which needs kitty 0.40 or newer. In other terminals, or at badge_scale = 1, they render at normal font size — the row is otherwise unchanged.

File-Based Trackers

Monitor time elapsed since events logged in text files (useful for tracking system updates, backups, etc.):

[trackers]
enabled = true
update_file = "/home/user/.config/update.txt"
backup_file = "/home/user/.config/backup.txt"
show_last_update = true
show_last_backup = true
last_update_icon = "󰚰"     # Nerd font icon for last update
last_backup_icon = "󰁯"     # Nerd font icon for last backup
label_color = "magenta"     # Optional: custom color for all tracker labels

Smart Time Display:

  • Automatically shows the most appropriate time unit:
    • Less than 1 hour: "X minutes ago"
    • Less than 24 hours: "X hours ago"
    • 1 day: "1 day ago"
    • More than 1 day: "X days ago"

Automatic Warning System:

  • Last Backup turns red with a warning icon once the backup is more than backup_warn_hours old (default 7, so 8 hours and up).
  • Last Update turns red once the update is more than update_warn_days old (default 7).
  • Example: 󰚰 Last Update 10 days ago ⚠️ (shown in red)
[trackers]
backup_warn_hours = 7   # warn when the last backup is older than this
update_warn_days = 7    # warn when the last update is older than this

File Format:

The tracker files should contain a single date on the first line in any of these formats:

  • "7/9/2025 01:27AM" - US format with 12-hour time
  • "2025-07-09T01:27:00" - ISO 8601 format
  • "2025-07-09 14:30:00" - Date with 24-hour time
  • "2025-07-09" - Date only (uses file modification time for the time component)

Example:

# Update the last update time
echo "2026-01-03" > ~/.config/update.txt

# Or with timestamp for more precision:
date '+%m/%d/%Y %I:%M%p' > ~/.config/update.txt

# Or with a script after running system updates:
#!/bin/bash
sudo pacman -Syu  # or your update command
date '+%Y-%m-%d %H:%M:%S' > ~/.config/update.txt

Output Examples:

󰚰 Last Update: 15 minutes ago
󰁯 Last Backup: 3 hours ago
󰚰 Last Update: 2 days ago
󰁯 Last Backup: 1 day ago

Use Cases:

  • Track time since last system update
  • Monitor backup schedules (especially useful for frequent backups)
  • Track maintenance windows
  • Monitor any event logged with a timestamp
  • Automatic backup tracking with borgmatic or similar tools

Section Breaks

Organize your output by adding blank lines after specific fields:

[display]
# Add blank lines after Shell and Theme to separate sections
section_breaks = ["Shell", "Theme", "Disk"]

Important: Use the exact label text as it appears in the output, not the config field names. For example:

  • Use "NixOS Generations" (not "nix_generations")
  • Use "System Age" (not "system_age")
  • Use "WM" (not "window_manager")
  • Use "OS" (not "distro")

Custom Label Colors

Override the default label color for specific fields:

[display.label_colors]
CPU = "yellow"
GPU = "yellow"
Memory = "green"
Disk = "green"
"NixOS Generations" = "magenta"
"System Age" = "blue"

Logo Position

Configure where the logo/image appears relative to the system information:

[display]
logo_position = "left"   # Options: "left", "top", "right"
  • left (default): Logo appears on the left side with info aligned to the right
  • top: Logo appears above the info with configurable column layout
  • right: Logo appears on the right side with info on the left

Note: Logo positioning needs the kitty image protocol (kitty or Ghostty). If the image cannot be loaded, every position falls back to the ASCII logo.

Column Layout (Top Position Only)

When using logo_position = "top", you can choose between single or double column layout:

[display]
logo_position = "top"
column_layout = "two"   # Options: "two", "one"
  • two (default): Info displayed in two columns for better space utilization
  • one: Info displayed in a single centered column beneath the logo

This setting only applies when logo_position = "top". For other positions, it has no effect.

Logo Size

Adjust the size of the logo/image displayed:

[display]
logo_size = 300   # Size in pixels (width)

The logo size is specified in pixels (width). The height is automatically calculated to maintain the image's aspect ratio.

  • Smaller values (e.g., 200): Compact display, takes less terminal space
  • Default (300): Balanced size for most use cases
  • Larger values (e.g., 500, 800): Bigger, more prominent logo

Note: Very large sizes may not fit well in smaller terminal windows.

Anime Mode

Use anime or custom artwork images instead of distro logos. This works with all logo positions (left, right, top).

Adding Your Own Anime Images:

Simply drop PNG files into the assets/ directory following this naming convention:

  • anime.png (always checked first)
  • anime2.png
  • anime3.png
  • anime4.png
  • ... and so on (up to 100 images)

The program automatically detects all available images and cycles through them sequentially with each run. Each time you run mattfetch, it shows the next image in the sequence, wrapping back to the first image after reaching the last one. This ensures you see all your images over time!

Note: The cycle counter is stored in /tmp/mattfetch-anime-counter. To reset and start from the first image, delete this file.

Configuration:

[display]
anime_mode = true

# Option 1: Use a custom anime image (outside assets/)
anime_image_path = "/home/user/Pictures/my-anime.png"

# Option 2: Choose a specific built-in anime (1-N where N = number of images found)
# 1 = anime.png, 2 = anime2.png, 3 = anime3.png, etc.
anime_builtin = 3

# Option 3: Sequential cycling (default)
# If anime_builtin is not set, images cycle sequentially with each run

# Optional: Set custom size in pixels (width)
# If not set, uses the default logo_size setting (300px)
anime_size = 400

Command line:

# Enable anime mode (cycles through built-in anime)
mattfetch --anime

# Combine with other options
mattfetch --anime --logo-position top

# Reset the cycle to start from first image
rm /tmp/mattfetch-anime-counter

Image Selection Priority:

  1. If anime_image_path is set and the file exists, it will be used
  2. Program scans assets/ for all anime*.png files (supports gaps in numbering)
  3. If anime_builtin is set (1-N), that specific built-in anime is used
  4. Otherwise, images cycle sequentially from the available list
  5. Falls back to checking ~/mhome/Pictures/Logos/ directory if assets not found

Sizing:

  • Anime images use the logo_size setting by default (300px)
  • Set anime_size to use a custom size specifically for anime mode
  • Sizes are automatically clamped between 50-2000 pixels for safety

This allows you to customize your fetch display with your favorite artwork while keeping all the layout and positioning features.

Now Playing

Shows the currently playing track. Off by default, since it shells out to an external tool.

[modules]
now_playing = true

[display]
now_playing_format = "{{artist}} - {{title}}"
# now_playing_player = "spotify"   # restrict to one player; omit for whichever is active
now_playing_max_len = 45           # truncate long tracks; 0 disables

The player is chosen first, over D-Bus via busctl (it ships with systemd, so no extra package is needed). If several players are on the bus at once — a paused browser tab alongside a music player — whichever is actually Playing is preferred, then a paused one; a stopped player is never shown. Then:

  1. playerctl, if installed, is asked about that player. It applies the format string itself and supports the most placeholders.
  2. Without playerctl, the track read over D-Bus is formatted by mattfetch.
  3. If busctl is unavailable or finds nothing, playerctl's own choice of player is used, then mpc current for mpd, which exposes no MPRIS interface of its own.

Use now_playing_player to pin one; it matches case-insensitively against part of the bus name, so "sonic" selects org.mpris.MediaPlayer2.sonic_tui.

now_playing_format accepts playerctl's placeholders. The D-Bus backend supplies {{artist}}, {{title}}, {{album}} and {{status}}; anything else playerctl understands (such as {{duration(mpris:length)}}) is removed rather than printed literally, and a separator left dangling by an empty field is trimmed. The format is not applied to the mpc fallback, which returns whatever mpd's own format produces.

When nothing is playing the line is omitted. When none of the three backends is installed it reads unavailable (install playerctl) instead of going blank, since a blank line is indistinguishable from silence and gives no hint that a tool is missing.

Truncation counts terminal columns, so a title in a wide script (CJK, emoji) is cut at the same on-screen length as a Latin one, and never mid-character.

ANSI Color Blocks

Displays the terminal's 16 ANSI colors as a row of blocks at the bottom of the output — handy when testing themes.

[modules]
colors = true

[display]
color_block_width = 3   # cells per block, 1-8

Two rows are drawn: normal colors 0–7 on top, bright 8–15 below. Blocks are rendered as background color over spaces rather than a glyph, so they look the same in every font.

Showing hex or RGB values alongside them is not supported: the actual values come from your terminal's palette, and reading it back requires a query-and-response round trip that mattfetch deliberately avoids.

Border

Add a decorative border around the fetch output:

[display]
show_border = true
border_color = "cyan"    # Optional: cyan, red, green, yellow, blue, magenta, white, black
border_style = "rounded" # Optional: "rounded", "solid", "dotted", or "doubled"

Border Styles:

  • rounded (default): Rounded corners with solid lines (╭─╮│╰╯)
  • solid: Square corners with solid lines (┌─┐│└┘)
  • dotted: Square corners with dotted lines (┌┄┐┆└┘)
  • doubled: Square corners with double lines (╔═╗║╚╝)

Border Color: You can customize the border color independently from other colors. Available colors: cyan, red, green, yellow, blue, magenta, white, black.

Note: Borders are drawn only when no logo is shown at all, i.e. with show_logo = false (or --no-logo). They are not drawn around image or ASCII-art layouts.

Module Descriptions

Module Description
hostname System hostname
username Current user
uptime System uptime
distro Linux distribution name and version
kernel Linux kernel version
desktop Desktop Environment (DE)
window_manager Window Manager or Compositor (Hyprland, Sway, i3, etc.)
theme Current theme (via hyprchanger.sh, waybar, or GTK)
cpu CPU model and core count
gpu GPU model
memory RAM usage (used/total)
disk Root partition usage
system_age Time since system installation
nix_generations Number of NixOS generations
shell Current shell (bash, zsh, fish, etc.)
boot_time How long the last boot took (via systemd-analyze)
packages Package counts from detected package managers (nix, pacman, apt, dnf, flatpak, snap, etc.)
now_playing Currently playing track — off by default, needs playerctl or mpc
colors The terminal's 16 ANSI colors as a row of blocks — off by default

Display Modes

Normal Mode

Displays information alongside an image (in kitty and Ghostty) or a multi-color ASCII art logo (everywhere else):

          ▗▄▄▄       ▗▄▄▄▄    ▄▄▄▖     matt@nixos
          ▜███▙       ▜███▙  ▟███▛     ──────────
           ▜███▙       ▜███▙▟███▛      OS: NixOS 23.11
            ▜███▙       ▜██████▛       Kernel: 6.1.0
     ▟█████████████████▙ ▜████▛  ▟▙    Uptime: 2d 5h 30m
    ▟███████████████████▙ ▜███▙ ▟██▙   WM: Hyprland
           ▄▄▄▄▖           ▜███▙▟███▛  Theme: catppuccin-mocha
          ▟███▛             ▜██▛▟███▛  CPU: AMD Ryzen 9 5900X (24)
         ▟███▛               ▜▛▟███▛   Memory: 15.2GB / 32.0GB

Compact Mode

Minimal single-line output:

matt | nixos | up 2d 5h 30m | NixOS 23.11 | 6.1.0

Use with --compact flag or set compact = true in config.

Tips & Tricks

Integration with Shell Prompt

Add to your .bashrc or .zshrc:

# Show mattfetch on new terminal
mattfetch

Show Only Specific Information

Disable unwanted modules in the config:

[modules]
hostname = true
username = true
uptime = true
# Disable everything else
distro = false
kernel = false
# ... etc

By default the logo is chosen from the detected distro. To pick a different one, set image_path to either a bundled asset name or a path to your own image:

[display]
image_path = "bluefin-3"                    # bundled asset, ".png" optional
# image_path = "/home/user/Pictures/me.png" # or any file of your own

Bundled assets are resolved wherever mattfetch is installed, so a plain name works the same from a source checkout, a Nix profile or a Homebrew Cellar.

Assets are searched in this order:

  1. assets/ in the current directory — debug builds only (cargo run from a checkout). An installed release build skips it, so running mattfetch inside an unrelated project with its own assets/ folder can't change the logo.
  2. share/mattfetch/assets/ next to the installed binary.
  3. ~/mhome/Pictures/Logos/distros/, then ~/mhome/Pictures/Logos/.

Scaled logos are cached in ~/.cache/mattfetch/, keyed on the image's path, size, modification time and the target width, so resizing a large image is paid once.

SVG is supported. Vector logos are rasterised at exactly logo_size, so they stay sharp at any size and scale up as well as down — a raster asset is never enlarged beyond its own resolution.

Given a name without an extension, .svg is preferred over .png within the same directory, so replacing assets/nixos.png with assets/nixos.svg needs no config change. Location still outranks format, though: the search order above is applied first, so a nixos.svg sitting in ~/mhome/Pictures/Logos/ will not override a nixos.png that ships with the program. Give an explicit extension (image_path = "nixos.png") to pin one format regardless.

Text inside an SVG will not render: no font database is loaded, because enumerating system fonts would cost more than everything else mattfetch does. Logos drawn as paths — which is essentially all of them — are unaffected.

Distro logos: arch, bluefin, cachyos, debian, endeavouros, fedora, gentoo, manjaro, mint, nixos, opensuse, pop_os, ubuntu, void

Project Bluefin artwork: bluefin-2, bluefin-3, bluefin-4, bluefin-5, bluefin-6, dakota, karl

To add your own ASCII art logo, edit src/ascii_art.rs and add a new logo function.

Development

Built with:

  • Rust 2021 edition
  • serde & toml for configuration
  • colored for terminal colors
  • sysinfo for system information
  • clap for CLI argument parsing

Contributing

Contributions welcome! Feel free to:

  • Add new system information modules
  • Add new ASCII art logos
  • Improve detection algorithms
  • Fix bugs

TO-DO

  • Actually Add ASCII Art (multi-color ASCII art from fastfetch)
  • Add in the ability for the fetch to change the logo depending on which distro you use
  • Look into using svgs instead
  • Work on better terminal compatibility (ASCII art fallback for non-Kitty terminals)
  • Make it faster — in progress: only configured modules are collected now, package managers and custom scripts run concurrently, nix-store -qR and NixOS generations are cached per system generation, and scaled logos are cached. --custom-scripts-only went from 34 ms to 1 ms.
  • Make Nix Package
  • Make Arch Package
  • Make Homebrew formula
  • Publish to AUR
  • Tag v0.7.0 and point the Homebrew formula at it
  • Add a rustfmt.toml and run a formatting pass so CI can check formatting

Potential New Features

  • Network Information Module

    • Local IP address(es)
    • WiFi SSID (for wireless connections)
    • Network interface name
    • Connection type (WiFi/Ethernet)
  • Battery Status (for Laptops)

    • Battery percentage
    • Charging status (charging/discharging/full)
    • Time remaining estimate
    • Battery health indicator
    • Battery icon with different states
  • Package Manager Detection & Counts

    • Auto-detect package managers (apt, pacman, dnf, nix, flatpak, snap, etc.)
    • Show counts for all detected package managers
    • Combine multiple managers (e.g., "Packages: 1,234 (nix), 42 (flatpak)")
  • Terminal Color Palette Display

    • Display the 16 ANSI colors as colored blocks
    • Show RGB/Hex values — needs a terminal query round trip, deliberately avoided
    • Useful for theme testing and terminal configuration
    • Toggleable module (colors) and a --colors flag
  • Temperature Monitoring

    • CPU temperature
    • GPU temperature (if available)
    • Optional warning colors (e.g., red if >80°C)
    • Integration with sensors command on Linux
    • Show highest temp sensor by default
  • Other Ideas

    • Now Playing (current track via playerctl/MPRIS, or mpc for mpd)
    • Display/Monitor Info (resolution, refresh rate, multi-monitor setup)
    • Quotes/Fortune (random quote or fortune cookie at the top/bottom)
    • Boot Time (how long the last boot took)
    • JSON Export (--json flag for scripting/automation)

License

MIT License - feel free to use and modify as needed.

Acknowledgments

Inspired by neofetch, fastfetch, and other system fetch tools.

ASCII Art: Multi-color ASCII logos sourced from fastfetch (MIT License). Ubuntu logo from neofetch PR #2125.

Note, this fetch was created 90% by Claude Code. 10% of me going in and fixing the nonsense that comes with AI. I've done this mostly for fun.