- Rust 94.2%
- Roff 3.4%
- Nix 1.4%
- Ruby 0.5%
- Shell 0.5%
|
Some checks failed
CI / check (push) Has been cancelled
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>
|
||
|---|---|---|
| .forgejo/workflows | ||
| assets | ||
| Formula | ||
| src | ||
| .envrc | ||
| .gitignore | ||
| ARCH_PACKAGING.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| config.example.toml | ||
| default.nix | ||
| flake.lock | ||
| flake.nix | ||
| LICENSE | ||
| mattfetch.1 | ||
| PKGBUILD | ||
| PKGBUILD-git | ||
| PKGBUILD-local | ||
| README.md | ||
| rustfmt.toml | ||
| screenshot.png | ||
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.
Table of Contents
- Features
- Installation
- Usage
- Configuration
- Module Descriptions
- Display Modes
- Tips & Tricks
- Development
- Contributing
- TO-DO
- License
- Acknowledgments
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'sIDandID_LIKEas 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
- Reads from
-
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.
With Flakes (Recommended)
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
commandvalues run throughsh -con 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"
- Less than 1 hour:
Automatic Warning System:
- Last Backup turns red with a warning icon once the backup is more than
backup_warn_hoursold (default 7, so 8 hours and up). - Last Update turns red once the update is more than
update_warn_daysold (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.pnganime3.pnganime4.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:
- If
anime_image_pathis set and the file exists, it will be used - Program scans
assets/for all anime*.png files (supports gaps in numbering) - If
anime_builtinis set (1-N), that specific built-in anime is used - Otherwise, images cycle sequentially from the available list
- Falls back to checking
~/mhome/Pictures/Logos/directory if assets not found
Sizing:
- Anime images use the
logo_sizesetting by default (300px) - Set
anime_sizeto 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:
playerctl, if installed, is asked about that player. It applies the format string itself and supports the most placeholders.- Without playerctl, the track read over D-Bus is formatted by mattfetch.
- If busctl is unavailable or finds nothing, playerctl's own choice of player is
used, then
mpc currentfor 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
Custom Logo
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:
assets/in the current directory — debug builds only (cargo runfrom a checkout). An installed release build skips it, so running mattfetch inside an unrelated project with its ownassets/folder can't change the logo.share/mattfetch/assets/next to the installed binary.~/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 -qRand NixOS generations are cached per system generation, and scaled logos are cached.--custom-scripts-onlywent 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--colorsflag
-
Temperature Monitoring
- CPU temperature
- GPU temperature (if available)
- Optional warning colors (e.g., red if >80°C)
- Integration with
sensorscommand 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 (
--jsonflag 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.
