fuzzel.ini(5)

📦
version 1.15.0 · 11 versions
, in arch rolling

💅 fuzzel.ini — the config file for fuzzel(1), bestie edition ✨

okay so this is the File Formats Manual page for fuzzel.ini, and honestly? it's giving "let me customize my launcher exactly how i want" energy. come sit with me, we're going through it 🫶

🌸 NAME 🌸

fuzzel.ini — the configuration file for fuzzel(1). that's it, that's the name, iconic 💅

🎀 DESCRIPTION 🎀

bestie. fuzzel uses the standard unix configuration format, with section-based key/value pairs. the default section is usually unnamed, i.e. not prefixed with a [section]. but lowkey it can also be explicitly named [main], say if it needs to be reopened after any of the other sections. iykyk ✨

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

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

and! 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 you can peek at that if you want a vibe check 💖

🔥 SECTION: main 🔥

this is the main character section. let's go, option by option, no cap 🧚

include

Absolute path to configuration file to import.

the imported file has its own section scope. i.e. the including configuration is still in the default section after the include, regardless of which section the included file ends in. so no, it doesn't leak, we love a clean boundary ✨

  • The path must be an absolute path, or start with ~/.
  • Multiple include directives are allowed, but only one path per directive.
  • Nested imports are allowed. (inception but make it config files 🌀)

Default: not set.

namespace

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. like, protect the girls (the passwords) 🙈

Default: launcher

output

Output (monitor) to display on. you can list the available outputs with wlr-randr or with Sway using swaymsg -t get_outputs.

Example: DP-1

Default: Not set-- let the compositor choose output.

font

Comma separated list of fonts to use, in fontconfig format. that is, a font name followed by a list of colon-separated options. most noteworthy is :size=n, which is used to set the font size. note that the font size is also affected by the dpi-aware option. see FONT CONFIG below for details 👑

Examples:

  • Dina:weight=bold:slant=italic
  • Courier New:size=12
  • Fantasque Sans Mono:fontfeatures=ss01

Default: monospace.

use-bold

Boolean. when set, fuzzel may use bold fonts. for example, for the currently selected item.

Default: no

dpi-aware

auto, yes, or no. three little choices, one big vibe decision 💀

  • when set to yes, fonts are sized using the monitor's DPI, making a font of a given 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.
  • when set to 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.
  • finally, if set to 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-blending

Boolean. when enabled, fuzzel will 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 "technically correct, socially confusing" 💀

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. slay 🔥

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. the font was literally designed under different lighting, bestie 🎀

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. the limit does not exist? it does, actually 🙈

placeholder

Text to display as placeholder in the input box.

Default: empty.

prompt

String to use as input prompt. note that trailing spaces are trimmed, unless the string is quoted.

Default: "> ".

message

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. for details on how long lines are treated, see message-mode 💖

message-mode

One of wrap, and expand.

  • wrap: any line that is longer than width is wrapped to the following line. wraps on space boundaries if available, trimming leading spaces caused by truncation. if no space is available, the line is broken up after width characters.
  • expand: if the longest line in message is longer than width, make the dialogue box wider to accommodate message. (main character solution: just get bigger ✨)

icon-theme

Icon theme. note that the name is case sensitive.

Default: default.

icons-enabled

Boolean. when enabled, application icons (from the selected icon-theme) will be rendered.

Default: yes.

hide-before-typing

Boolean. when enabled, application list will be hidden until the first letter is typed. when the prompt is cleared again, the list will appear. mysterious. elusive. only appears when you type. 🦋

Default: no.

fields

Comma separated list of XDG Desktop entry fields to match against.

even though fuzzel only displays the application names, matching can (and by default is) be done against other fields as well. supported fields are:

  • filename
  • name
  • generic
  • exec
  • categories
  • keywords
  • comment

"filename" is the .desktop file name.

Default: filename,name,generic.

password-character

Default character to use with the command line option --password. note that this can be overridden on the command line, by explicitly specifying the character with --password=X.

Default: *.

match-mode

One of exact, fzf and fuzzy.

  • exact: what you type is matched exactly against each field in the fields list.
  • fzf: fzf-style matching, where substrings from what you have typed are matched against each field in the fields list.
  • fuzzy: levenshtein-based fuzzy matching of what you have typed against each field in the fields list.

Default: fzf

sort-result

Boolean. whether to sort the result or not. disabling sorting means no comparisons will be made between match results. i.e. launch count, match length, etc will be ignored. this effectively disables the cache (though, the cache is still updated on exit).

disabling this can improve search latency when searching very large data sets. speed demon behavior ⚡

Default: yes

match-counter

Boolean. when enabled, the match count and total count is displayed on the right-hand side of the input prompt. disabling the counter also improves performance when loading a very large number of dmenu entries from STDIN.

Default: no.

filter-desktop

Boolean. filter desktop files based on the value of XDG_CURRENT_DESKTOP.

Default: no.

show-actions

Boolean. some desktop files define "actions", in addition to the application itself. examples are "new window", "preferences", etc. when this option is enabled, those actions will be listed by fuzzel. the extra lore 🫶

Default: no.

terminal

terminal command to use when launching 'terminal' programs.

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: $TERMINAL -e.

list-executables-in-path

Boolean. when enabled, the list will include executables from the PATH environment variable.

Default: no.

launch-prefix

Prefix to add before argv of executed program. if set, fuzzel will pass desktop file metadata through environment variables:

  • DESKTOP_ENTRY_ID (also exported as FUZZEL_DESKTOP_FILE_ID for backward compatibility)
  • DESKTOP_ENTRY_PATH
  • DESKTOP_ENTRY_NAME
  • DESKTOP_ENTRY_COMMENT
  • DESKTOP_ENTRY_NAME_L (Localized)
  • DESKTOP_ENTRY_COMMENT_L (Localized)
  • DESKTOP_ENTRY_ICON

And if launching an action:

  • DESKTOP_ENTRY_ACTION (Action identifier)
  • DESKTOP_ENTRY_ACTION_NAME
  • DESKTOP_ENTRY_ACTION_NAME_L (Localized)
  • DESKTOP_ENTRY_ACTION_ICON

Default: not set.

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

Horizontal margin away from the anchor point in pixels.

Default: 0.

⚠️ Also, quick note for the option right before this one: this option has no effect when anchor=center, top or bottom.
  • y-margin — vertical margin away from the anchor point, in pixels. Default: 0. Heads up: no effect when anchor=center, left or right.
  • lines — number of matches to show. Default: 15.
  • hide-prompt — boolean. When set, hides the prompt line, making the window smaller. Input is still accepted even though the prompt line isn’t displayed. Cannot be used with prompt-only. Default: no.
  • minimal-lines — boolean. Adjusts the number of lines to display to the minimum of lines and the number of input lines. Only effective in dmenu mode. This lets fuzzel size itself to the actual number of input lines instead of always showing the full lines rows. Default: no.
  • width — window width, in characters. Margins and borders are not included. For variable width fonts this is an estimate, because the exact number of characters that fit depends on which characters are being displayed. Default: 30.
  • tabs — number of spaces a tab is expanded to. Default: 8.
  • horizontal-pad — horizontal padding, in pixels, between border and content. Default: 40.
  • vertical-pad — vertical padding, in pixels, between border and content. Default: 8.
  • inner-pad — vertical padding between prompt and match list, in pixels. Default: 0.
  • image-size-ratio — the ratio of the large image displayed when there are only a “few” matches, compared to the full window size. Set to 0 or 1 to disable the large images. Default: 0.5.
  • line-height — override line height from font metrics. Default: use font metrics.
  • letter-spacing — additional letter spacing. Negative values are allowed. Default: 0.
  • layer — 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 — 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 will immediately close fuzzel; using exit-on-keyboard-focus-loss=no allows interacting with other windows while fuzzel is open.
    • Default: exclusive.
  • exit-on-keyboard-focus-loss — boolean. If true, exit when the fuzzel window loses keyboard focus. Setting this to false 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 (<= 1.7) exhibits this behavior, for example. Default: yes.
  • render-workers — 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. In case you have a ridiculous amount of cores and/or threads, consider limiting the number of render-workers, since fuzzel cannot parallelize more than the number of displayed entries.
  • match-workers — 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. In case you have a ridiculous amount of cores and/or threads, consider limiting the number of match-workers, since fuzzel cannot parallelize more than the number of available entries.
  • delayed-filter-ms — time, in milliseconds, to delay refiltering when there are more matches than delayed-filter-limit. Default: 300.
  • delayed-filter-limit — when there are more matches than this, switch from immediate refiltering to delayed refiltering (see delayed-filter-ms). Default: 20000.
  • scaling-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.
  • cache — specify the default cache location. If unset, $XDG_CACHE_HOME/fuzzel will be used. Set to /dev/null to disable caching. Default: not set.
  • auto-select — boolean. When one entry is left, automatically select it. Default: no.
  • enable-mouse — boolean. Enable mouse input. Default: yes.

🎨 COLORS 🎨

All color values are in RGBA. Slay, but make it hexadecimal, bestie. 💅

  • background — background color. Default: fdf6e3ff.
  • text — text (foreground) color of unselected entries. Default: 657b83ff.
  • message — text (foreground) color of the message string. Default: 657b83ff.
  • prompt — text (foreground) color of prompt character(s). Default: 586e75ff.
  • placeholder — text (foreground) color of the placeholder string. Default: 93a1a1ff.
  • input — text (foreground) color of input string. Default: 657b83ff.
  • match — text (foreground) color of the matched substring. Default: cb4b16ff.
  • selection — background color of the selected entry. Default: eee8d5ff.
  • selection-text — text (foreground) color of the selected entry. Default: 586e75ff.
  • selection-match — text (foreground) color of the matched substring of the selected entry. Default: cb4b16ff.
  • counter=HEX — the color of the match count stats printed at the right-hand side of the input prompt. See COLORS. Default: 93a1a1ff.
  • border — border color. Default: 002b36ff.

🎀 BORDER 🎀

  • width — width of the border, in pixels. Default: 1.
  • radius — amount of corner “roundness.” Default: 10.
  • selection-radius — amount of corner “roundness” for the selected entry. Default: 0.

🍓 DMENU 🍓

  • mode — one of text or index. Determines what fuzzel prints on stdout when an entry is selected: text prints the entry itself, index prints the index of the selected entry. Index values start at zero for the first entry. Default: text.
  • exit-immediately-if-empty — boolean. If enabled, fuzzel will not run at all (i.e. it will not open a window, and will not print anything on stdout) if there’s nothing on stdin. Default: no.

🎹 SECTION: key-bindings

okay so this is where you take the wheel 🫶 — this section is literally just for overriding the default key bindings.

The general format is action=combo1...comboN. Which means: every action can have one or more key combos, and you separate them with spaces, bestie. Each combination looks like mod1+mod2+key. And the modifiers AND the key both have to be valid XKB key names — no inventing your own, sorry 💅

⚠️ Heads up: if Shift is one of your modifiers, the key must not be in upper case. Like, Control+Shift+V will never trigger. Ever. But Control+Shift+v will. The way that capital V just ghosts you 😭

Also: Alt is usually called Mod1. Yes, it's giving chaos, but that's just how it is.

xkbcli interactive-wayland is genuinely useful for finding keysym names 🔍 — it's the main character tool for that job.

okay and this part is important 💀 — a key combination can only be mapped to one action. Say you wanna bind Control+k to next. Since that's already the default shortcut for delete-line-forward, you must unmap the default binding first. How? Set action=none. Like: delete-line-forward=none. periodt.

  • cancel — quits fuzzel without executing anything at all. Default: Control+g Control+c Control+bracketleft Escape.
  • execute — runs the currently selected entry. Or, in dmenu mode, prints the selected entry on stdout instead. Default: Return KP_Enter Control+y.
  • execute-or-next — if there's exactly one match, it executes it (or in dmenu mode, prints the selected entry on stdout). If there's more than one match, it selects the next entry instead. It wraps around when you hit the last entry. Default: Tab.
  • execute-input — executes the raw input exactly as-is, no matter whether it matches anything in the list or not 🫣 In dmenu mode it prints the selected entry on stdout instead. Default: Shift+Return Shift+KP_Enter.
  • cursor-left — moves the cursor one character to the left. Default: Left Control+b.
  • cursor-left-word — moves the cursor one whole word to the left. Default: Control+Left Mod1+b.
  • cursor-right — moves the cursor one character to the right. Default: Right Control+f.
  • cursor-right-word — moves the cursor one whole word to the right. Default: Control+Right Mod1+f.
  • cursor-home — yeets the cursor to the beginning of the input. Default: Home Control+a.
  • cursor-end — yeets the cursor to the end of the input. Default: End Control+e.
  • delete-line-backward — deletes everything before the cursor. Default: Control+u.
  • delete-line-forward — deletes everything after the cursor. Default: Control+k.
  • delete-line — deletes the entire input, all of it, gone 💀 Default: Control+Shift+BackSpace.
  • delete-prev — deletes the character before the cursor. Default: BackSpace Control+h.
  • delete-prev-word — deletes the word before the cursor. Default: Mod1+BackSpace Control+BackSpace Control+w.
  • delete-next — deletes the character after the cursor. Default: Delete.
  • delete-next-word — deletes the word after the cursor. Default: Mod1+d Control+Delete.
  • insert-selected — copies the selected entry into the prompt, replacing whatever's currently there. In application mode the Exec line gets inserted; in dmenu mode the entry itself is used. Default: Control+Tab.
  • expunge — removes the currently selected entry from the cache (the cache of most commonly launched applications). Default: Shift+Delete.
  • clipboard-paste — pastes from the clipboard. Default: Control+v XF86Paste.
  • primary-paste — pastes from the primary selection. Sidenote: this action is also bound to the middle mouse button, and that part is currently not configurable 🙈 Default: Shift+Insert Shift+KP_Insert.
  • prev — selects the previous entry. Does not wrap around when you reach the first entry. Default: Up Control+p.
  • prev-with-wrap — selects the previous entry, and does wrap around when you hit the first entry. Default: ISO_Left_Tap. (that's Shift+Tab btw 💅)
  • prev-page — switches to the previous page. Default: PageUp KP_PageUp.
  • next — selects the next entry. Does not wrap around when you reach the last entry. Default: Down Control+n.
  • next-with-wrap — selects the next entry, and does wrap around when you hit the last entry. Default: unbound.
  • next-page — switches to the next page. Default: Page_Down KP_Page_Down.
  • first — selects the first entry, on the first page. Default: Control+Home.
  • last — selects the last entry, on the last page. Default: Control+End.
  • custom-1, custom-2, ..., custom-19 — executes the currently selected entry, then exits with a non-zero exit code 🔥 custom-1 exits with exit code 10, custom-2 with 11, custom-3 with 12, and so on.

Default:

  • custom-1: Mod1+1
  • custom-2: Mod1+2
  • custom-3: Mod1+3
  • custom-4: Mod1+4
  • custom-5: Mod1+5
  • custom-6: Mod1+6
  • custom-7: Mod1+7
  • custom-8: Mod1+8
  • custom-9: Mod1+9
  • custom-10: Mod1+10
  • custom-11: Mod1+11
  • custom-12: Mod1+12
  • custom-13: Mod1+13
  • custom-14: Mod1+14
  • custom-15: Mod1+15
  • custom-16: Mod1+16
  • custom-17: Mod1+17
  • custom-18: Mod1+18
  • custom-19: Mod1+19

🔤 FONT CONFIG

okay so fontconfig uses a flexible string format for specifying fonts — it lets you define font families, styles, weights, and a bunch of other properties. The basic syntax follows this pattern:

"Family Name:style=Style:weight=Weight:size=Size"

Common properties:

  • family — the font family name
  • style — italic, oblique, roman
  • weight — light, normal, bold, black (or numeric values 100-900)
  • size — point size
  • slant — italic, oblique, roman
  • width — condensed, normal, expanded

Fontconfig supports fallback fonts 🧚 You can list multiple font families separated by commas. Fallback fonts get searched in the order they appear. And if a glyph can't be found in any of the fallback fonts, then the dynamic fallback list from fontconfig (for the primary font) gets searched. Example:

"My Custom Font, DejaVu Sans:weight=bold, sans-serif"

Fontconfig always returns something unless you literally have no fonts installed — no cap, regardless of what font name you give it 😭 You can check which fonts would be matched with fc-match -s YourFontName.

The font library Fuzzel uses, fcft, will search the explicit fallbacks whenever a glyph can't be found in the primary font. And when it can't find a glyph in the explicit fallbacks either, it searches the fontconfig fallbacks of the first font in Fuzzel's list. 🦋

This whole design lets you have a custom fallback sequence AND custom font options for each fallback. iconic, honestly.

👀 SEE ALSO

aaaand that's the whole page bestie, you made it to the end 🎀✨ this beauty's from the fuzzel.ini(5) manual, dated 2026-10-24 — go forth and configure, you absolute icon 👑💖

📦 where this page comes from