Omarchy WezTerm Migration Guide

[hikarisakamoto]

Guide to replacing Alacritty with WezTerm in Omarchy.

1. Install WezTerm

First, you need to install WezTerm onto your machine:

omarchy-pkg-add wezterm

2. Configure WezTerm & Omarchy Theming

WezTerm uses a Lua configuration file. To make it a "first-class" Omarchy app we need to set it up:

Create WezTerm's Main Config

First, create the WezTerm configuration directory and its main settings file. This file tells WezTerm to load Omarchy's generated colors.

~/.config/wezterm/wezterm.lua

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Hyprland/Wayland specific fixes
config.enable_wayland = true
config.window_decorations = "NONE"

return config

3. Update Live Integration Scripts

Update Omarchy's helper scripts on your live system. These are located in ~/.local/share/omarchy/bin/:

• bin/omarchy-font-set: Add WezTerm font modification.

  ~/.local/share/omarchy/bin/omarchy-font-set

  if [[ -f ~/.config/wezterm/wezterm.lua ]]; then
    sed -i "s/config.font = .*/config.font = wezterm.font(\"$font_name\")/g" ~/.config/wezterm/wezterm.lua
  fi

• bin/omarchy-restart-terminal: Hot-reload WezTerm by touching its config.

  ~/.local/share/omarchy/bin/omarchy-restart-terminal

  if [[ -f ~/.config/wezterm/wezterm.lua ]]; then
    touch ~/.config/wezterm/wezterm.lua
  fi

• bin/omarchy-launch-screensaver: Add WezTerm as a first-class citizen in the switch-case for screensavers. Just like Alacritty, Kitty, and Ghostty, WezTerm needs to use hyprctl dispatch exec -- to span across all monitors correctly. Find the case $terminal in statement and add the WezTerm block right at the top:

  ~/.local/share/omarchy/bin/omarchy-launch-screensaver

    *WezTerm*|*wezterm*)
      hyprctl dispatch exec -- \
        wezterm start --class=org.omarchy.screensaver \
        --config-file=~/.local/share/omarchy/default/wezterm/screensaver.lua \
        -e omarchy-cmd-screensaver
      ;;

4. Update Live Desktop Environment & Hyprland

Make WezTerm the default terminal environment in your live Window Manager.

• ~/.config/xdg-terminals.list: Replace Alacritty.desktop with org.wezfurlong.wezterm.desktop.

  Note: Omarchy uses xdg-terminal-exec to launch your terminal from Hyprland via SUPER+RETURN. The name in this list MUST exactly match the name of WezTerm's actual .desktop file on your system!

  If SUPER + RETURN still launches Alacritty, it means xdg-terminal-exec couldn't find WezTerm's desktop file under the name provided. You can find the exact, correct filename by running:

  find /usr/share/applications ~/.local/share/applications -name "*wezterm*" -o -name "*WezTerm*"

  Put the exact filename it returns at the very top of your xdg-terminals.list.

• ~/.config/waybar/config.jsonc: Change "on-click-right": "alacritty" to "wezterm". To apply this change immediately, run:

  omarchy-restart-waybar

• ~/.config/hypr/input.conf: You do not need to delete Alacritty! Terminal emulators handle Wayland touchpad scrolling speeds very differently. To safely add WezTerm as a first-class app while keeping Alacritty as a backup, add a new dedicated statement for WezTerm just like Ghostty has:

  ~/.config/hypr/input.conf

  windowrule = match:class org.wezfurlong.wezterm, scroll_touchpad 1.0
  

  Note: If you run WezTerm via XWayland (enable_wayland = false) in a VM, this rule will not apply to it because XWayland translates the scroll events differently!

• ~/.local/share/omarchy/default/hypr/apps/terminals.conf: Add org.wezfurlong.wezterm to the terminal tag regex.

Note: You will need to reload Hyprland to apply these changes. You can do this immediately by running:

hyprctl reload

5. Remove Alacritty (Optional)

Once you are completely satisfied that WezTerm is working as expected and fully integrated, you can safely remove Alacritty from your machine.

sudo pacman -Rns alacritty

You can also clean up its configuration files:

rm -rf ~/.config/alacritty
rm ~/.local/share/applications/Alacritty.desktop

6. Pitfalls & Troubleshooting

Debugging WezTerm Crashing on Launch

If WezTerm simply refuses to launch from the app menu (especially in VMs), the best way to debug it is to run it from your current terminal (like Alacritty) and force it to spawn a new process so you can read the error logs directly.

wezterm start --always-new-process

If it is a graphics issue, the error output will usually complain about Wayland EGL, Vulkan, or OpenGL contexts failing to initialize.

Wayland & GPU Frontends (VMs / Zink Errors)

If you are testing in a VM, you might see errors like libEGL warning: failed to create dri2 screen or MESA: error: ZINK: vkCreateInstance failed. This happens because WezTerm tries to use native Wayland EGL/Vulkan, but your VM lacks hardware 3D acceleration, causing Mesa's Vulkan translation (Zink) to fail.

The Fix for VMs: Force WezTerm to run through XWayland instead of native Wayland. XWayland has a much more robust software-rendering fallback for VMs. In your ~/.config/wezterm/wezterm.lua, change these settings:

~/.config/wezterm/wezterm.lua

-- Change this from true to false:
config.enable_wayland = false
config.front_end = "Software" -- or "OpenGL"

This tells WezTerm to launch as an X11 window, which Hyprland will perfectly handle via XWayland, bypassing the missing Wayland Vulkan drivers in your VM.

Startup Time

WezTerm takes ~100-200ms longer to launch than Alacritty because it spawns a multiplexer daemon. Consider using wezterm-gui or wezterm cli spawn in your Hyprland bindings for instant spawning.

Font Rendering Engine

WezTerm uses HarfBuzz. Fonts might look slightly different (thicker/taller) than in Alacritty. You may need to tweak config.line_height or config.freetype_load_target = "Light".

Wayland Class Quirks

When launching specific app classes (like the screensaver), WezTerm sometimes appends metadata to Wayland app-ids. Use partial matches or regex in Hyprland window rules instead of exact string matching

Hope this help you migrate!
Don't forget to improve your wezterm.lua to better fit you UI experience!
Keep coding!