fuzzel(1)

📦
version 1.15.0 · 11 versions
, in arch rolling

🎀 fuzzel(1) 🎀

okay so this is the General Commands Manual page for fuzzel, and bestie we are going to read the whole thing together because it's lowkey iconic ✨

🌸 NAME 🌸

fuzzel — Wayland app launcher and picker 🫶

⭐ SYNOPSIS ⭐

fuzzel [OPTIONS]...

💖 DESCRIPTION 💖

As a launcher, fuzzel lists all available XDG applications in a searchable window. that's the whole vibe, she's a launcher 👑

With the --dmenu flag, fuzzel works like a general-purpose picker like dmenu, rofi or fzf. Options to choose from are provided on the STDIN and the selected option is printed to STDOUT. literally pipe in, pick out, slay 💅

The search box supports Emacs-like key bindings. your hands already know what to do, no cap 💜

Many things can be configured with fuzzel.ini(5) or command line options:

  • --config=PATH — path to configuration file, see fuzzel.ini(5) for details.
  • --check-config — verify configuration and then exit with 0 if ok, otherwise exit with 1. a little vibe check for your config 🧚
  • -n, --namespace=NAMESPACE — specifies the namespace for the spawned layer shell surface. Useful for blocking fuzzel out from screencasts in your compositor if it shows sensitive information, such as passwords. privacy queen behavior 🙈 Default: launcher
  • --cache=PATH — use a custom cache location. fuzzel uses this file to cache the most commonly launched applications (to be able to sort them at the top). yes she remembers your favorites 💖 You can also use this option to enable caching of dmenu entries. It is recommended that you use a separate cache file for each "type" of dmenu invocation; i.e. one for the browser history, another for emojis etc. Set to /dev/null to disable caching. (girl bye to the cache 💀) Default: XDG_CACHE_HOME/fuzzel
  • --override=[SECTION.]KEY=VALUE — override an option set in the configuration file. If SECTION is not given, defaults to main. Explicit command line options always override both the on-disk configuration, and any --override used. For example:
fuzzel --prompt hello --override prompt=world

Here, the prompt will be set to hello. the command line said it first, periodt ✋

  • -o, --output=OUTPUT — specifies the monitor to display the window on. Autocompletion is available for zsh and fish, or you can list the available outputs with wlr-randr or with Sway using swaymsg -t get_outputs. Example: DP-1 Default: let the compositor choose output.
  • -f, --font=FONT[,FALLBACK1,FALLBACK2,...] — comma separated list of primary font, and fallback fonts, in FontConfig format. See FONT FORMAT. Default: monospace.
  • --use-bold — allow fuzzel to use bold fonts. bold is a lifestyle 💅
  • -D, --dpi-aware=no|yes|auto — how fonts get sized, and this one is a whole saga, so:
    • yes — fonts are sized using the monitor's DPI, making a font of a given point size have the same physical size, regardless of monitor. In this mode, the monitor's scaling factor is ignored; doubling the scaling factor will not double the font size.
    • no — the monitor's DPI is ignored. The font is instead sized using the monitor's scaling factor; doubling the scaling factor does double the font size.
    • auto — fonts will be sized using the monitor's DPI if all monitors have a scaling factor of 1. If at least one monitor as a scaling factor larger than 1 (regardless of whether the fuzzel window is mapped on that monitor or not), fonts will be scaled using the scaling factor.
    • Note that this option typically does not work with bitmap fonts, which only contains a pre-defined set of sizes, and cannot be dynamically scaled. Whichever size (of the available ones) that best matches the DPI or scaling factor, will be used. 😭
    • Also note that if the font size has been specified in pixels (:pixelsize=N, instead of :size=N), DPI scaling (dpi-aware=yes) will have no effect (the specified pixel size will be used as is). But, if the monitor's scaling factor is used to size the font (dpi-aware=no), the font's pixel size will be multiplied with the scaling factor. Default: auto
  • --gamma-correct — do gamma-correct blending in linear color space. This is how font glyphs are supposed to be rendered, but since nearly no applications or toolkits are doing it on Linux, the result may not look like you are used to. it's giving "correct but nobody else is doing it" 🦋
    • Compared to the default (disabled), bright glyphs on a dark background will appear thicker, and dark glyphs on a light background will appear thinner.
    • FreeType can limit the effect of the latter, with a technique called stem darkening. It is only available for CFF fonts (OpenType, .otf) and disabled by default (in FreeType). You can enable it by setting the environment variable FREETYPE_PROPERTIES="cff:no-stem-darkening=0" before starting fuzzel.
    • Also be aware that many fonts have been developed on systems that do not do gamma-correct blending, and may therefore look thicker than intended when rendered with gamma-correct blending, since the font designer set the font weight based on incorrect rendering.
    • In order to represent colors faithfully, higher precision image buffers are required. For this reason, fuzzel uses 16-bit image buffers (instead of 8-bit) when gamma-correct blending is enabled.
    • It is not possible to enable gamma-correct blending in cairo enabled builds of fuzzel, since cairo does not support 16-bit image buffers.
  • -p, --prompt=PROMPT — prompt to use. Default: > (that's a greater-than sign and then a space, don't @ me).
  • --prompt-only=PROMPT — same as --prompt, but in --dmenu mode it also:
    • does not read anything from STDIN
    • sets --lines to 0

In non-dmenu mode it behaves exactly like --prompt.

  • --hide-prompt — hide the prompt line, making the window smaller. Input is still accepted, but the prompt line is not displayed. This option cannot be used at the same time with --prompt-only. pick a lane bestie 🙈
  • --placeholder=TEXT — text to display as placeholder in the input box. Default: empty.
  • --mesg=STRING — message to display above the prompt. Can contain some informational message, or can be used for having your prompt be above the input instead of in front. Supports newlines.
  • --mesg-mode=wrap|expand — how to handle lines in --mesg when they are longer than --width. See fuzzel.ini(5) for details. The default is wrap.
  • --search=TEXT — initial search/filter string. This option pre-fills the input box with the specified string, letting you pre-filter the result. pre-gaming the filter, we love to see it ⭐
  • -i — ignored; for compatibility with other, similar utilities (where -i means "case insensitive search"). she's just being polite 🫶
  • --icon-theme=NAME — icon theme to use. Note that this option is case sensitive; the name must match the theme's folder name. Example: Adwaita Default: default
  • -I, --no-icons — do not render any icons. minimalism era 🎀
  • --hide-before-typing — hide application list until something is typed.
  • -F, --fields=FIELDS — comma separated list of XDG Desktop entry fields to match against:
    • filename: the .desktop file's filename
    • name: the application's name (title)
    • generic: the application's generic name
    • exec: the applications's executable, as specified in the desktop file. Note: may include command line options as well.
    • keywords: the application's keywords
    • categories: the application's categories
    • comment: the application's comment

Default: filename,name,generic

  • --password=[CHARACTER] — password input. Render all typed text as CHARACTER. If CHARACTER is omitted, a * will be used. no peeking 👀
  • -T, --terminal=TERMINAL ARGS — command to launch XDG applications with the property Terminal=true (htop, for example). The command may contain the placeholder {cmd} which will be replaced with the actual command to be run. When {cmd} is present, the command is only substituted in those locations and is not appended at the end. Examples:
    • foot -a '{cmd}' -T '{cmd}' {cmd} sets app-id and title to the command name, then executes it
    • xterm -e {cmd} executes the command in xterm
    • xterm -e (no {cmd}) uses old behavior: appends command after terminal args

Default: not set.

  • -a, --anchor=ANCHOR — set window anchor, i.e. where on screen the window will be displayed. You can choose one from:
    • top-left
    • top
    • top-right
    • left
    • center
    • right
    • bottom-left
    • bottom
    • bottom-right

Default: center

  • --x-margin=MARGIN — horizontal margin away from the anchor point in pixels. Default: 0. Note: this option has no effect when anchor=center, top or bottom.
  • --y-margin=MARGIN — vertical margin away from the anchor point in pixels. Default: 0. Note: this option has no effect when anchor=center, left or right.
  • --select=STRING — select the first entry that matches the given string (case insensitive).
  • --auto-select — automatically select when only one match remains. she chooses for you, no thoughts needed 💅
  • --select-index=INDEX — select the entry with index, not compatible with --select. it's one or the other, bestie 🦋
  • -l, --lines=COUNT — the (maximum) number of matches to display. This dictates the window height. Default: 15.
  • --minimal-lines — adjust the number of lines to display to the minimum of --lines and the number of input lines. Only effective in dmenu mode. This allows fuzzel to size itself to the actual number of input lines rather than always showing the full --lines rows.
  • -w, --width — window width, in characters. Margins and borders not included. For variable width fonts this is an estimate, as the exact number of characters that will fit depends on which characters are being displayed. Default: 30.
  • --tabs=COUNT — number of spaces a tab is expanded to. Default: 8.
  • -x, --horizontal-pad=PAD — horizontal padding between border and icons and text. In pixels, subject to output scaling. Default: 40.
  • -y, --vertical-pad=PAD — vertical padding between border and text. In pixels, subject to output scaling. Default: 8.
  • -P, --inner-pad=PAD — vertical padding between prompt and match list. In pixels, subject to output scaling. Default: 0.
  • -b, --background=HEX — background color. See COLORS. Default: fdf6e3ff.
  • -t, --text-color=HEX — text color. See COLORS. Default: 657b83ff.
  • --message-color=HEX — message color. See COLORS. Default: 657b83ff.
  • --prompt-color=HEX — text (foreground) color of prompt character(s). See COLORS. Default: 586e75ff.
  • --placeholder-color=HEX — text (foreground) color of the placeholder string. See COLORS. Default: 93a1a1ff.
  • --input-color=HEX — text (foreground) color of input string. See COLORS. Default: 657b83ff.
  • -m, --match-color=HEX — the color of matching substring(s). As you start typing in the search box, the matching part in each application’s name is highlighted with this color. See COLORS. Default: cb4b16ff.
  • -s, --selection-color=HEX — the color to use as the background of the currently selected application. See COLORS. Default: eee8d5ff.
  • -S, --selection-text-color=HEX — the text color of the currently selected application. See COLORS. Default: 586e75ff.
  • -M, --selection-match-color=HEX — the color of matching substring(s) of the currently selected application. As you start typing in the search box, the matching part in each application’s name is highlighted with this color. See COLORS. Default: cb4b16ff.
  • --selection-radius=INT — the border radius of the selection entry. Like border-radius, this is subjected to output scaling. A larger value means a rounder corner. 0 disables rounded corners. Default: 0.
  • --counter-color=HEX — the color of the match count stats printed at the right-hand side of the input prompt. See COLORS. Default: 93a1a1ff.
  • -B, --border-width=INT — the width of the surrounding border, in pixels (subject to output scaling). Default: 1.
  • -r, --border-radius=INT — the corner curvature, subject to output scaling. Larger means more rounded corners. 0 disables rounded corners. Default: 10.
  • -C, --border-color=HEX — the color of the border. See COLORS. Default: 002b36ff.
  • --show-actions — include desktop actions in the list. Desktop actions are alternative actions some desktop entries have. Examples include "New Window", "New Document", etc.
  • --match-mode=exact|fzf|fuzzy — defines how what you type is matched. See fuzzel.ini(5) for details. The default is fzf.
  • --no-sort — do not sort the result.
  • --counter — display the match count.
  • --filter-desktop=[no] — filter the visible desktop entries based on the value of XDG_CURRENT_DESKTOP. If the optional parameter is "no", explicitly disables filtering (that is, it overrides the value in the config).
  • --fuzzy-min-length=VALUE — search strings shorter than this will not be fuzzy matched. Default: 3.
  • --fuzzy-max-length-discrepancy=VALUE — maximum allowed length difference between the search string and a fuzzy match. Larger values result in more fuzzy matches. Default: 2.
  • --fuzzy-max-distance=VALUE — maximum allowed levenshtein distance between the search string and a fuzzy match. Larger values result in more fuzzy matches. Default: 1.
  • --line-height=HEIGHT — override line height from font metrics. In points by default, but can be specified as pixels by appending 'px' (i.e. --line-height=16px). Default: not set.
  • --letter-spacing=AMOUNT — additional space between letters. In points by default, but can be specified as pixels by appending 'px' (i.e. letter-spacing=5px). Negative values are supported. Default: 0.
  • --layer=top|overlay — which layer to render the fuzzel window on. Valid values are top and overlay.
    • top renders above normal windows, but typically below fullscreen windows and lock screens.
    • overlay renders on top of both normal windows and fullscreen windows. Note that the order is undefined if several windows use the same layer. Since e.g. lock screens typically use overlay, that means fuzzel may or may not appear on top of a lock screen.

Default: overlay

  • --keyboard-focus=exclusive|on-demand — keyboard focusing mode. Valid modes are exclusive and on-demand.
    • exclusive locks keyboard focus to fuzzel, receiving all keyboard input until closed.
    • on-demand makes fuzzel focus like a regular window, allowing other windows to take keyboard focus by e.g. clicking on them. By default, switching keyboard focus immediately closes fuzzel; using --no-exit-on-keyboard-focus-loss lets you interact with other windows while fuzzel is open.

Default: exclusive

  • --no-exit-on-keyboard-focus-loss — do not exit when losing keyboard focus. This can be useful on compositors where enabling "focus-follows-mouse" causes fuzzel to exit as soon as the mouse is moved over another window. Sway (at least up to, and including 1.7) exhibits this behavior.
  • --launch-prefix=COMMAND — command to launch XDG applications with. If set, fuzzel will pass the Desktop File ID of the chosen application (see the Desktop Entry specification) in the DESKTOP_ENTRY_ID environment variable (also exported as FUZZEL_DESKTOP_FILE_ID for backward compatibility). Default: not set.
  • --list-executables-in-path — include executables from the PATH environment variable. Applies to the normal application mode, not the dmenu mode.
  • --render-workers=COUNT — number of threads to use for rendering. Set to 0 to disable multithreading. Default: the number of available logical CPUs (including SMT). Note that this is not always the best value. In some cases, the number of physical cores is better.
  • --match-workers=COUNT — number of threads to use for matching. Set to 0 to disable multithreading. Default: the number of available logical CPUs (including SMT). Note that this is not always the best value. In some cases, the number of physical cores is better.
  • --delayed-filter-ms=TIME_MS — time, in milliseconds, to delay refiltering when there are more matches than --delayed-filter-limit. Default: 300.
  • --delayed-filter-limit=N — when there are more matches than this, switch from immediate refiltering to delayed refiltering (see --delayed-filter-ms). Default: 20000.
  • --scaling-filter=FILTER — scaling filter to use when down scaling PNGs. One of none, nearest, bilinear, box, linear, cubic, lanczos2, lanczos3 and lanczos3-stretched.
    • none, nearest and bilinear are the fastest options, but also have the worst looking results.
    • cubic, lanczos2, lanczos3 and lanczos3-stretched are the slowest options, with the best looking results.
    • box, and to some degree linear, are in the middle, performance wise, while in most cases still being just as, or close to, as good as cubic and the lanczos filters.

Default: box

  • -d, --dmenu — dmenu compatibility mode. In this mode, the list entries are read from stdin (newline separated). The selected entry is printed to stdout. If the input string does not match any of the entries, the input string is printed as is on stdout.

Alternatively, you can symlink the fuzzel binary to dmenu. Fuzzel will then start in dmenu mode, without the --dmenu argument.

Fuzzel also supports PNG and SVG icons, using Rofi’s extended dmenu protocol. To set an icon for an entry, append \0icon\x1f<icon-name>. Example:

echo -en "Firefox\0icon\x1ffirefox" | fuzzel --dmenu

Fallback icons using comma-separated values are also supported. When the primary icon is not found, subsequent icons in the list will be tried until one is successfully loaded. Example:

echo -en "Firefox\0icon\x1ffirefox,web-browser,application-x-executable" | fuzzel --dmenu
  • --dmenu0 — like --dmenu, but input is NUL separated instead of newline separated. Note that in this mode, icons are not supported.
  • --index — print selected entry’s index instead of its text. Index values start with zero for the first entry. dmenu mode only.
  • --with-nth=N|FMT — display the N:th column (1-based, tab separated by default, see --nth-delimiter) of each input line. When selected, the full input line is printed on stdout. dmenu mode only.

The argument can also be a format string (i.e free-format text), where {N} expands to the N:th column. Ranges of the form {N..M} and {N..} (open-ended) are also supported.

Note that in posix compliant shells, ranges ({N..M}) must be in quotation marks to prevent the shell from expanding it.

Example:

printf "1\tFirst\n2\tSecond" | fuzzel -d --with-nth=2

This will display the entries First and Second. When one of them is selected, the full input line (tabs included) is printed on stdout.

Setting it to 0 is the same as not specifying --with-nth at all.

  • --accept-nth=N|FMT — output the N:th column (1-based, tab separated by default, see --nth-delimiter) of each input line to stdout. dmenu mode only.

The argument can also be a format string (i.e free-format text), where {N} expands to the N:th column. Ranges of the form {N..M} and {N..} (open-ended) are also supported.

Note that in posix compliant shells, ranges ({N..M}) must be in quotation marks to prevent the shell from expanding it.

Example:

printf "1\tFirst\n2\tSecond" | fuzzel -d --accept-nth=2

This will display the entries 1 First and 2 Second. Depending on which one is selected, First or Second will be printed to stdout.

Setting it to 0 is the same as not specifying --accept-nth at all.

  • --match-nth=N|FMT — match against the N:th column (1-based, tab separated by default, see --nth-delimiter) of each input line. This is instead of matching against the displayed value (which can be changed with --with-nth).

The argument can also be a format string (i.e free-format text), where {N} expands to the N:th column. Ranges of the form {N..M} and {N..} (open-ended) are also supported.

Note that in posix compliant shells, ranges ({N..M}) must be in quotation marks to prevent the shell from expanding it.

Example:

printf "123\t456\t789" | fuzzel -d --with-nth=1 --accept-nth=2 --match-nth=3

This will display the entry 123, but matching will only be done against 789 (specifically, 123 will not match). When selected, 456 is printed on stdout.

Setting it to 0 is the same as not specifying --match-nth at all.

  • --nth-delimiter=CHARACTER — field (column) delimiter for --with-nth and --accept-nth. Must be a single ASCII character. Default: \t (tab).
  • --only-match — do not allow custom entries, only return a selected item. In this mode, fuzzel always returns an entry. It will not return if no matching entry is selected.

The exception to this is the execute-input key binding, which always executes/selects the input text.

  • -R, --no-run-if-empty — exit immediately, without showing the UI, if stdin is empty. dmenu mode only.
  • --log-level={info,warning,error,none} — sets the log level, and it applies to both the log output on stderr and syslog. Default is warning, bestie.
  • --log-colorize=[{never,always,auto}] — turns colorization of the log output on stderr on or off. That's the whole vibe: pretty logs or plain logs.
  • --log-no-syslog — kills syslog logging entirely. After this, logging only happens on stderr. No cap.
  • --print-timing-info — prints timing info to help you debug performance issues. It's giving "why is this slow" energy, and honestly we love a diagnostic icon.
  • --no-mouse — disables mouse input. Sorry to the mouse girlies, this one's not for you.
  • -v, --version — shows the version number and quits. Iconic, brief, slays, leaves.

🔎 SEARCH PATHS 🔎

So here's the tea: fuzzel goes looking for XDG .desktop files following the XDG Base Directory Specification (link's at the bottom, iykyk), and it looks in the applications subdirectory of the paths given by XDG_DATA_DIRS and XDG_DATA_HOME.

By default, those paths are:

  • ~/.local/share/applications
  • /usr/local/share/applitions
  • /usr/share/application
Yes, bestie, those last two are spelled exactly like that in the manpage — applitions and application. Not my typo, not me being cute, that's literally the source. Copy at your own risk 💀

See the specification for the details, fr fr.

⚙️ CONFIGURATION ⚙️

fuzzel will search for a configuration file in these locations, in this exact order:

  1. XDG_CONFIG_HOME/fuzzel/fuzzel.ini (defaulting to ~/.config/fuzzel/fuzzel.ini if unset)
  2. XDG_CONFIG_DIRS/fuzzel/fuzzel.ini (defaulting to /etc/xdg/fuzzel/fuzzel.ini if unset)

An example configuration file containing all the options with their default value commented out will usually be installed to /etc/xdg/fuzzel/fuzzel.ini. So there's a whole starter pack waiting for you 🎀

For more info, see fuzzel.ini(5).

🌍 LOCALIZATION 🌍

Fuzzel uses the localized strings from the .desktop files by default. Want it to stop doing that? Run fuzzel with LC_MESSAGES=C. That's it, that's the whole trick ✨

⌨️ IME ⌨️

Fuzzel supports input method editors (IME) via the text-input-unstable-v3 Wayland protocol. So if you type in languages that need an IME, you're covered, bestie 🫶

🖋️ FONT FORMAT 🖋️

The font is specified in FontConfig syntax. Which is basically: a colon-separated list of font name and font options.

Examples:

  • Dina:weight=bold:slant=italic
  • Arial:size=12

That's the whole format. Very demure, very mindful 🎀

🌈 COLORS 🌈

Every single color must be specified as a RGBA quadruple, in hex format, with no leading '0x'. Like, none. Do not.

EXAMPLES:

  • white: ffffffff (no transparency)
  • black: 000000ff (no transparency)
  • black: 00000010 (semi-transparent)
  • red: ff0000ff (no transparency)

And the default color scheme is Solarized. Taste, honestly 👑

📁 FILES 📁

  • $XDG_CACHE_HOME/fuzzel — stores a list of applications and their launch count. This is what lets fuzzel sort frequently launched applications at the top, which is basically the app equivalent of knowing your order at the coffee shop. Main character behavior ☕
  • $XDG_RUNTIME_DIR/fuzzel-$WAYLAND_DISPLAY.lock — lock file, used to prevent multiple fuzzel instances from running at the same time. One fuzzel at a time, babe, we don't do chaos here 🙈

👀 SEE ALSO 👀

And that's the whole page, bestie! This edition of the manual is dated 2026-10-24, and it's the fuzzel(1) page — go forth, launch your apps, and stay cunty 💅✨🦋

📦 where this page comes from