om-custom-font

Install font files on Omarchy 4 and wire them into the system properly.

Why this exists

Omarchy handles fonts well, as long as the font is packaged. It does not handle font files:

That last row is the gap. A font you bought, downloaded from a foundry, built yourself, or that simply isn't packaged has no path in. There's nothing wrong with Omarchy's design here — it just assumes a package manager, and some fonts don't come that way.

To be clear about what is not a gap: omarchy font list is fc-list :spacing=100, so it's fully dynamic — once a font is installed by any means it shows up and is selectable. And omarchy install font is a general command, not a fixed menu; the curated list of six is only the GUI shortcut, and you can add your own rows to ~/.config/omarchy/extensions/omarchy-menu.jsonc.

Is this tool worth it?

The manual equivalent is genuinely short:

cp Font.ttf ~/.local/share/fonts/ && fc-cache -f && omarchy font set "Family Name"

If that's all you need, do that. omarchy-font-set accepts any installed family, so it works fine.

What the tool adds is the parts that are fiddly rather than long:

• Family-name detection via fc-query — the name is rarely the filename (CascadiaCode.ttf → CaskaydiaMono Nerd Font), and omarchy font set fails on a wrong guess.
• Variable vs. traditional detection — warns before you install one file of a nine-file family and get synthetic bold for the next six months.
• Whole-directory installs with family disambiguation when an archive contains several.
• The GTK side — monospace-font-name is a separate setting from fontconfig's monospace alias, and Omarchy 4 doesn't set it.
• A reset path back to stock, including the stale-config check below.
• A stale Omarchy 3 fontconfig override detector — see below; this one is a real silent failure.

Targets Omarchy 4

Omarchy 4 ("Quattro") replaced Waybar, Walker, Mako, SwayOSD, hyprlock, hypridle, swaybg, and polkit-gnome with a single Quickshell-based omarchy shell, and made fontconfig the single source of truth for font resolution. Earlier releases of this tool targeted Omarchy 3 and no longer apply.

Installation

Two paths — pick whichever fits how you use Omarchy.

As an Omarchy plugin (with a Quickshell overlay)

omarchy plugin add https://github.com/whiskeytuesday/om-custom-font.git --enable
omarchy restart shell

The shell restart is needed once, after install, so the overlay is wired into the shell's toggle machinery. Skip it and the overlay won't appear even though the plugin is enabled.

Opening the overlay. Two ergonomic paths — pick either or both. The raw IPC (omarchy-shell shell toggle io.github.whiskeytuesday.custom-font) works but is verbose:

1. From the Omarchy menu. Add one line to ~/.config/omarchy/extensions/omarchy-menu.jsonc:

   "install.font-file": {"icon":"","label":"Font from file","action":"omarchy-shell shell toggle io.github.whiskeytuesday.custom-font"},
   

   Then Super+Shift+Space → type "font" → Enter. It lives next to omarchy install font, where it belongs.

2. From a terminal (or a keybind). Symlink the wrapper this repo ships:

   ln -s ~/.config/omarchy/plugins/io.github.whiskeytuesday.custom-font/bin/omarchy-custom-font ~/.local/bin/
   

   Now omarchy-custom-font opens the overlay. Bind it to a key if you want:

   # ~/.config/hypr/bindings.conf
   bind = SUPER SHIFT, F, exec, omarchy-custom-font
   

Once open: pick a .ttf/.otf from the inline file browser, tick Set as shell default, choose whether GTK follows, hit Install. The overlay is a thin GUI on top of the CLI below.

To remove:

omarchy plugin remove io.github.whiskeytuesday.custom-font --yes

Removing the plugin does not touch fonts you already installed with it, or the system font state. If you want a clean slate as well, run om-custom-font reset-all before removing (the overlay's Reset to Omarchy defaults button does the same thing).

As a plain CLI

cp om-custom-font ~/.local/bin/
chmod +x ~/.local/bin/om-custom-font

Usage

# Install and set as system default
om-custom-font set ~/Downloads/MyFont.ttf
om-custom-font set ~/FontFamily/                    # directory with full family

# Also update GTK apps (file dialogs, GTK-based apps)
om-custom-font set ~/Downloads/Font.ttf --gnome
om-custom-font set ~/Downloads/Font.ttf --gnome-mono   # monospace only
om-custom-font set ~/Downloads/Font.ttf --gnome-font   # UI font only

# Install without setting as default (adds to the Omarchy font menu)
om-custom-font add ~/Downloads/Font.ttf

# Show current font settings across all systems
om-custom-font current

# Reset everything to Omarchy defaults
om-custom-font reset-all

# Restore previous GNOME settings from backup
om-custom-font revert-gnome

Font size is not this tool's job

This tool sets font family. Omarchy 4 owns font size through one knob that moves the shell, GTK, and terminals in lockstep:

omarchy display text size          # show current
omarchy display text size 16       # set (9-20 px)
omarchy display text size reset    # back to defaults (12px / 1.0 / 9pt)

It is also exposed in the shell's Display panel as the Text size slider.

The knob is anchored at 12px:

om-custom-font never writes a size. The --gnome* flags swap the family and carry the existing point size over untouched, because omarchy-display-text-size computes text-scaling-factor by quantizing against the GTK font-name point size — writing that point size directly desyncs the knob.

--gnome-size=N existed in earlier versions and now errors out with a pointer to omarchy display text size. revert-gnome likewise restores only the two family settings; it deliberately does not restore text-scaling-factor, since putting back one third of a three-way knob is what causes the desync described below.

Known: text size looks unsynchronised with terminals

Reports of "it resizes system text but not terminal text" are usually one of:

• Coarse quantization. Terminal pt is round(px * 9/12), so 14px and 15px both land on 11pt — a slider step that visibly moves the shell may not move the terminal at all.
• No live reload. Kitty gets SIGUSR1 and Ghostty SIGUSR2, but Foot has no config-reload signal — running windows keep their startup size until relaunched. Omarchy sends a notification when it detects this.
• A stale config. omarchy-display-text-size rewrites terminal sizes with anchored sed patterns (^font-size = , ^size =, ^font_size , :size=). A hand-edited config that doesn't match those patterns is skipped silently.

om-custom-font current prints the shell/GTK/terminal values side by side so you can see which one is out of step.

How It Works

Font Installation

When you run set or add, the tool:

1. Copies font file(s) to ~/.local/share/fonts/
2. Updates the font cache with fc-cache
3. Detects the font family name automatically
4. For set, hands the family to omarchy-font-set

For directories, it installs all .ttf/.otf files and prompts you to choose a family if multiple are found.

Variable vs Traditional Fonts

The tool detects whether a font is:

• Variable font: single file containing all weights/styles (e.g. Adwaita Sans). Works fully from one file.
• Traditional font: separate files per weight/style (e.g. JetBrainsMono). Warns if you install only one file and suggests installing the directory.

What Gets Updated

omarchy-font-set does the system-wide work. In Omarchy 4 that is:

Waybar, SwayOSD, and hyprlock no longer exist in Omarchy 4 — they were absorbed into the omarchy shell, which follows fontconfig.

omarchy-font-set overwrites ~/.config/fontconfig/fonts.conf wholesale. Any hand-written fontconfig rules there will be lost. Put custom rules in ~/.config/fontconfig/conf.d/ instead.

Stale Omarchy 3 override

Omarchy 3 wrote a full ~/.config/fontconfig/fonts.conf using mode="assign". Omarchy 4's package-owned /etc/fonts/conf.d/50-omarchy.conf already assigns monospace, so a leftover assign-style user rule never matches and is silently ignored: terminals and GTK show your custom font while fc-match monospace still resolves to JetBrainsMono Nerd Font. Omarchy 4 uses mode="prepend_first", which wins.

om-custom-font current flags this as [STALE - Omarchy 3 format]. Fix it by re-applying the font:

omarchy font set "Your Font Family"

Monospace-only font menu

omarchy font list is fc-list :spacing=100, so only monospace families appear in the Omarchy font menu. A proportional family can still be set explicitly and works fine for GTK UI text, but won't be listed. The tool warns when the family you installed is not monospace.

GNOME/GTK Integration

Omarchy runs Hyprland, not GNOME, but GTK apps still read fonts from gsettings:

• File dialogs (open/save)
• GTK-based applications

GTK's monospace-font-name is a separate setting from fontconfig's monospace alias — without these flags your GTK text views stay on Adwaita Mono while everything else follows the font you set.

Use --gnome, --gnome-font, or --gnome-mono to update them. Each creates a timestamped backup of the two family settings that you can restore with revert-gnome. Omarchy 4 does not set these keys itself, so reset-all uses gsettings reset to return them to their schema defaults (Adwaita Sans 11 / Adwaita Mono 11).

Related Omarchy 4 commands

omarchy font list                  # available monospace fonts
omarchy font current               # fc-match monospace
omarchy font set <name>            # apply a family
omarchy install font <display-name> <package> <family>   # install any font *package*
omarchy display text size [n]      # the size knob

If your font is packaged, use omarchy install font — it's the blessed path and it keeps the font under the package manager, which this tool cannot do.

Requirements

• Omarchy 4 (provides omarchy-font-set, omarchy-font-current, omarchy-display-text-size)
• fontconfig (fc-cache, fc-query, fc-list, fc-scan, fc-match)
• gsettings (for the --gnome* options)

The plugin overlay additionally uses Qt6 declarative (Qt.labs.folderlistmodel for the inline directory browser, and FontLoader for the pangram preview), which the Omarchy shell already pulls in.

Testing

make lint      # bash -n, JSON check on manifest, qmllint on every .qml

For the overlay itself, bash -n + qmllint is the offline story; the visual pass is a real install:

omarchy plugin add file://$PWD --enable
omarchy-shell shell toggle io.github.whiskeytuesday.custom-font

A failed install is caught by the overlay's error banner rather than a broken shell — no scratch profile needed.

License

MIT