What Is matugen? The Beginner's Guide to Wallpaper-Driven Material You Theming

CodexFuse Team · 2026-11-04T14:55:05.691Z · 12 min read min read

What Is matugen, Exactly?

Matugen (pronounced "mat-uh-gen") is a cross-platform command-line tool that generates Material You color palettes from a wallpaper image or a single color. The project's own one-line definition, from the InioX/matugen repository, is "a cross-platform material you and base16 color generation tool" (source: InioX/matugen on GitHub). It is written in Rust, released under the GPL-2.0 license, and runs on Windows, Linux, macOS and NetBSD.

Give matugen a picture and the matugen Material You engine computes a full Material Design 3 (MD3) palette for you: primary, secondary, tertiary, surface, background, error and the rest of the standard color roles, each in light and dark variants. But generating colors is only half the job. What makes matugen special is what happens next: it injects the palette into templates you register in its configuration file, rewriting your status bar, launcher, terminal and shell configs so your entire desktop recolors itself the moment the wallpaper changes. If you want to see the basic idea of pulling colors out of a picture in your browser first, CodexFuse's image palette extractor demonstrates it — but extraction is not what matugen does, and that distinction is the whole point of the tool. Say it once, plainly: matugen generates harmonious Material Design 3 palettes using color science; it does not simply lift the dominant pixels out of your wallpaper.

As of this writing (2026-11-04), matugen is at version 4.2.0 (published 2026-08-17, per the GitHub releases API), and the repository has about 2,098 stars since its creation in March 2023. It has become the standard answer in Linux "ricing" circles to the question: how do I make my whole desktop match my wallpaper, automatically, every time?

How Does matugen Turn a Wallpaper Into a Theme?

The matugen wallpaper theming pipeline has five steps, and understanding them explains nearly everything about the tool:

1. Pick a source. Run matugen image path/to/wallpaper.jpg for an image, or matugen color hex "#ff0000" to theme from a single color (both from the official README quick start).
2. matugen chooses a source color. This seed color is what the entire palette derives from. You can steer the choice with the --prefer flag (darkness, lightness, saturation, less_saturation, value, or closest_to_fallback — needs version 4.1 or newer) or the source_color_index config option (0–4, where 0 is the most dominant). If no good color is found in an image, it falls back to fallback_color (#ffbf9b in the example config).
3. It computes a Material Design 3 scheme. You pick one of ten scheme variants with --type (for example --type scheme-vibrant), and a light, dark or smart mode with -m. The wiki's Usage page states the default scheme is scheme-tonal-spot when none is provided.
4. It populates every template in your config. Each template you registered in ~/.config/matugen/config.toml is rendered with the fresh palette and written to the real config file your app reads — your bar's CSS, your terminal's colors, your shell's theme file.
5. Hooks fire. pre_hook runs before generation and post_hook runs after, so you can do things like pkill -SIGUSR2 waybar to reload your bar the instant new colors land (per the official wiki).

That is the entire trick: one command, one wallpaper, every app recolored. No manual hex-code bookkeeping.

Should You Use matugen or pywal?

The matugen vs pywal debate is the most common beginner question — and with matugen explained side by side with pywal, the answer is clean. The two tools look similar — both take a wallpaper and produce colors — but their philosophies are opposites:

The distinction, sourced from the DeepWiki eww "Color Generation with Pywal and Matugen" page: "Pywal focuses on extracting actual colors present in the image" while "Matugen generates harmonious Material Design palettes inspired by the image." There is no rivalry here — matugen's own README lists pywal under "Other projects" — but if your mental model is "it copies my wallpaper's colors," reset it now. Matugen's output will look related to your wallpaper, not sampled from it, and that is deliberate: MD3 palettes are engineered to be readable and accessible, not just pretty.

Which Scheme and --prefer Setting Should You Pick?

Matugen ships ten scheme variants (verified in the project's src/scheme.rs). The wiki's Usage page says scheme-tonal-spot is used when you do not pass --type:

Beginners should start with the default and try scheme-vibrant and scheme-expressive against the same wallpaper to develop a feel for the range. Then there is the --prefer flag, which controls which candidate color becomes the seed. It needs matugen 4.1 or newer (PR #264, released 2026-03-22) — the duxlabs DMS docs confirm "the five --prefer modes need matugen 4.1 or newer and fall back to Dominant on anything older." The five are single-property sorts over the candidate colors; closest_to_fallback is the sixth value:

Pair these with -m light, -m dark or -m smart (smart picks dark or light automatically from the wallpaper's lightness), and --contrast (-1 to 1) if text readability needs tuning. That is the full color-decision surface: source, scheme, mode, contrast.

How Do Templates and config.toml Work?

Say it once, because everything else follows from it: your matugen config is a single TOML file plus mustache-style templates. On Linux the config lives at ~/.config/matugen/config.toml (Windows and macOS use their own platform paths; a custom path can be passed with -c).

In the config you register one [templates.<name>] block per app you want themed. Each block has an input_path (your template, full of keywords) and an output_path (the real config file matugen writes). From the official wiki: "You have to list all of your templates here by writing [templates.<name>]. Every template has an input and an output path. The input path is where your template with the keywords is. The output path is where the generated template with already replaced keywords should be written to."

Matugen templates put keywords inside {{ }} brackets and use dot notation. The MD3 form is {{ colors.<name>.<mode>.<format> }} — the wiki's own example is {{ colors.primary.default.hex }}. Formats cover everything an app config might need: hex, hex_stripped, rgb, rgba, hsl, individual channels like red/hue/lightness, and more. Base16 palettes use the parallel form {{ base16.base00.default.hex }}. You also get variables like {{ image }}, {{ mode }} and {{ scheme }}, chainable filters ({{ colors.primary.default.hex | lighten: 20.0 | invert }}), conditionals and loops in <* *> blocks, and \{{ }} to escape a literal bracket. A minimal template might look like this:

<* if {{ is_dark_mode }} *>
background = {{ colors.background.default.hex }}
foreground = {{ colors.on_background.default.hex }}
<* endif *>

One template per app, one config file, one command — and hooks like post_hook = "pkill -SIGUSR2 waybar" make the apps pick up the new colors immediately.

How Do You Install matugen and Run It for the First Time?

This matugen tutorial uses only the install routes documented in the project's README (verified 2026-11-04): cargo install matugen for any Rust setup, yay -S matugen-bin on Arch via the AUR, sudo pacman -S matugen from Arch's extra repository, pkgin install matugen on NetBSD, or the NixOS flake input with its Home Manager module for Nix users.

For your first run, put a wallpaper somewhere handy and run matugen image ~/Pictures/wallpaper.jpg. With no templates registered yet, matugen still generates the palette — add --json rgb to inspect it as JSON, or browse the candidate source colors with the image-colors command (new in 4.2.0). Then create your first [templates.test] block in ~/.config/matugen/config.toml pointing at a template for an app you actually use, re-run the same command, and watch the app's config file get rewritten. Most ricing happens on a personal Linux install, but if your development environment lives on a remote machine, our VPS hosting guide covers the server side of that setup.

Where Does matugen Fit in a Wayland Desktop?

Matugen is neither a compositor nor a desktop shell — it is the theming engine that sits underneath them. Your compositor manages windows; your shell draws the bar, dock, launcher and lock screen; matugen supplies the colors both of them wear. That layering is why it pairs so naturally with the current Wayland ecosystem: a native shell like Noctalia draws its entire interface from one place, and a launcher like Walker lives in the same desktop that matugen recolors — each template you add extends the one-command retheme to one more piece of the setup.

Think of the stack as three layers: the wallpaper (your taste), matugen (the color science), and your apps' config files (the consumers). Change layer one, run one command, and layer three follows. Nothing else on a typical Linux desktop closes that loop automatically.

What Mistakes Do Beginners Make with matugen?

Expecting it to copy the wallpaper's exact colors

The most common surprise is also the core concept: matugen generates an MD3 palette inspired by the image, not a sample of it. If you wanted literal dominant colors, that is pywal's job (see the comparison above).

Forgetting to register templates in config.toml

Running matugen image ... with an empty [templates] section generates a palette and writes it nowhere. The config file is the to-do list — no registered templates, no themed apps.

Using --prefer on an older matugen

The --prefer modes need version 4.1 or newer and silently fall back to the dominant color on older builds. Check with matugen --version before assuming your preference flag did anything.

Editing the generated files instead of the templates

The files at each template's output_path are overwritten on every run. Any hand edit there is temporary by design — make the change in the template, then re-run matugen.

Assuming scheme-smart works on any version

scheme-smart and smart mode arrived in 4.2.0. On 4.1.x and earlier, --type scheme-smart is not a valid choice — use an explicit scheme and -m smart for the light/dark decision instead.

Sources

• InioX/matugen README (definition, features, quick start, install routes) — github.com/InioX/matugen
• Official matugen docs/wiki (getting started, usage, configuration, templates) — iniox.github.io/#matugen
• Wiki: Usage (default scheme-tonal-spot, --type, --mode) — iniox.github.io/templates/matugen/usage.html
• Wiki: Configuration (config.toml paths, template registration, hooks) — iniox.github.io/templates/matugen/configuration.html
• Wiki: Templates (mustache syntax, MD3 roles, formats, filters, blocks) — iniox.github.io/templates/matugen/templates.html
• example/config.toml (fallback_color, prefer choices, source_color_index, contrast, wallpaper section) — github.com/InioX/matugen example config
• matugen v4.2.0 release notes (scheme-smart, source_color_index, image-colors) — releases/tag/v4.2.0
• matugen v4.1.0 release notes (PR #264, --prefer modes) — releases/tag/v4.1.0
• GitHub releases API (current version as of 2026-11-04: v4.2.0) — api.github.com/repos/InioX/matugen/releases/latest
• DeepWiki eww docs, "Color Generation with Pywal and Matugen" (pywal vs matugen distinction) — deepwiki.com/randomboi404/eww
• DeepWiki ZenithOS "Material You Theming System" (pipeline description) — deepwiki.com/zenith-56/zenithos
• duxlabs DMS application-themes docs (--prefer modes need 4.1+) — duxlabs.dev/docs/dms/application-themes
• DeepWiki nucleus-shell (scheme-neutral usage) — deepwiki.com/nucleus-hq/nucleus-shell
• Arch Linux package page for matugen (pacman install route) — archlinux.org/packages/extra/x86_64/matugen
• VS Code marketplace "Matugen Theme" extension (template token examples) — marketplace.visualstudio.com

Frequently Asked Questions

Is matugen a replacement for pywal?

Not exactly — they solve the same problem with opposite philosophies. Pywal extracts the colors actually in your image; matugen generates a Material Design 3 palette inspired by it. If you want your terminal to wear your wallpaper's literal pixels, pywal fits. If you want your whole desktop recolored with an accessible, harmonious MD3 theme from one command, matugen fits. Matugen's README lists pywal as a related project, not a rival.

Does matugen only work on Wayland?

No. Matugen generates colors and writes config files — it is not tied to any display protocol. It runs on Linux, Windows, macOS and NetBSD, and anything that reads the configs it writes (a Wayland bar, an X11 panel, a terminal emulator) gets themed the same way.

Which version do I need for --prefer and scheme-smart?

The --prefer source-color modes need matugen 4.1 or newer (older builds fall back to the dominant color). scheme-smart and smart mode need 4.2.0 or newer. The current release as of November 2026 is 4.2.0, so a fresh install has both.

Where is matugen's config file?

On Linux it is ~/.config/matugen/config.toml. Windows uses %AppData%\InioX\matugen\config\config.toml and macOS uses ~/Library/Application Support/com.InioX.matugen/config.toml, or pass any path with -c.

Can matugen set my wallpaper too?

Yes — the [config.wallpaper] section of config.toml lets you define a wallpaper-setting command (the example config uses swww), so one matugen run can change both the wallpaper and every theme derived from it.