WezTerm Configuration Cookbook

Introduction

Recently, I switched from Tera Term on Windows and iTerm2 on Mac to WezTerm. While I didn't have any major complaints with either Tera Term or iTerm2, Tera Term lacks true color support, and I felt that window activation in iTerm2 was a bit heavy, so I decided to make the switch.

Vim/Neovim themes displayed in true color look great, and above all, being able to write configurations in text is a very good experience that I've come to like. Regarding the heavy window activation, I feel like it hasn't changed much.

However, I struggled quite a bit with the configuration for the migration. So, I'll leave a record of the parts I struggled with in the form of something like a reverse lookup reference. I hope this proves useful to someone.

(One item in this article is not yet implemented. I'll write it when I feel like it.)

Reverse Lookup WezTerm Configuration

Specifying the window position at startup

It seems this cannot be handled simply through settings. It appears necessary to hook into gui-startup and pass the position via wezterm.mux.spawn_window.

wezterm.on('gui-startup', function()
    wezterm.mux.spawn_window({
        position = {
            x = 200,
            y = 100,
        },
    })
end)

Reference: Set initial window position before a window is created · Issue #2976 · wezterm/wezterm

Specifying the window size at startup

If you are satisfied with specifying the size in terms of character cells, you can simply set initial_cols and initial_rows.

config.initial_cols = 160
config.initial_rows = 40

While this works fine for my preference, I couldn't find a way to explicitly specify the actual window size as far as I searched.

Maximizing the window

To maximize the window, while it's possible on Mac by setting sufficiently large values for initial_cols and initial_rows, on Windows, this seemed impractical as it consumes excessive memory and takes time to start.

Even without doing that, there is a standard way to configure it. Just like Specifying the window position at startup, you hook into gui-startup.

wezterm.on('gui-startup', function()
    local _, _, window = wezterm.mux.spawn_window({})
    window:gui_window():maximize()
end)

Reference: maximize - Wez's Terminal Emulator

However, this method introduces an animation at startup on Mac. I personally use maximize on Windows and initial_cols/initial_rows on Mac.

Entering fullscreen

Use toggle_fullscreen instead of maximize from Maximizing the window.

wezterm.on('gui-startup', function()
    local _, _, window = wezterm.mux.spawn_window({})
    window:gui_window():toggle_fullscreen()
end)

Reference: toggle_fullscreen - Wez's Terminal Emulator

TODO: Customize window appearance

I would like to write about window_decorations, window_frame, and window_padding with screenshots.

Connecting to WSL via SSH on Windows

You can also connect to WSL via wslhost.exe using something like config.default_domain = 'WSL:Ubuntu', but connecting via SSH feels faster. In my environment, the time it took for the shell to initialize and start accepting input was about 1 second faster.

config.default_domain = 'wsl-ssh' -- Use the name specified in `config.ssh_domains.name`
config.ssh_backend = 'Ssh2'
config.ssh_domains = {
    {
        name = 'wsl-ssh', -- Can be anything
        remote_address = 'localhost:22', -- Adjust this if you've changed the port
        username = <USERNAME>,
        multiplexing = 'None',
    },
}

By configuring it as above, it connects to WSL at startup. There are a few traps in these settings, so I'll explain them briefly.

config.ssh_backend = 'Libssh' (default) does not support SSH agents

Libssh seems to have better support for things like cryptography, which is why it's the default. However, since Libssh does not support SSH agents, you must use Ssh2 if you want to connect using an SSH agent.

Usage of wezterm ssh with ssh-agent on Windows 11 · wezterm/wezterm · Discussion #3772 This discussion is somewhat related, but I haven't specifically configured ~/.ssh/config on the Windows side.

Note that SSH agent forwarding won't work with just this. If you also want agent forwarding, using wsl2-ssh-agent seems to be the best option currently as far as I know. (However, it doesn't seem to work with Pageant.)

Reference:
ssh_backend - Wez's Terminal Emulator
wsl2-ssh-agent: Bridge from WSL2 to ssh-agent.exe service

multiplexing = 'None' must be set to prevent crashes on connection

Without this setting, it seems WezTerm needs to be installed on the remote end.

Reference: object: SshDomain - Wez's Terminal Emulator

Using Japanese IME (AquaSKK/macSKK) on Mac

In iTerm2, there was a setting for AquaSKK, and just by turning it on, there were generally no issues with input... However, in WezTerm, AquaSKK/macSKK doesn't work well as is. Even during conversion, combination keys with Ctrl are captured by WezTerm, making it impossible to perform conversions properly.

You can handle this by configuring it as follows:

config.macos_forward_to_ime_modifier_mask = 'SHIFT|CTRL'

Reference: macos_forward_to_ime_modifier_mask - Wez's Terminal Emulator

By the way, when looking up Japanese input in WezTerm, the topic of config.use_ime often comes up. However, this setting seems to have become enabled by default a long time ago, so there's no need to worry about it now.

Adjusting other keyboard inputs on Mac

On Mac, various keys besides the Ctrl issue in IME don't seem to work well. I use the following three settings to work around this.

config.keys = {
  -- Ctrl+Q doesn't work
  { mods = 'CTRL', key = 'q', action = wezterm.action.SendString('\x11') },
  -- I want Ctrl+/ to be Ctrl+_
  { mods = 'CTRL', key = '/', action = wezterm.action.SendString('\x1f') },
  -- Not only does \ produce ¥, but it also doesn't work when you want to use \ as the Vim Leader
  { key = '¥', action = wezterm.action.SendString('\\') },
}

Reference:
CTRL-Q needs to be pressed twice to register in macOS · Issue #2630 · wezterm/wezterm
Wezterm preventing CTRL + / from entering vim · Issue #3180 · wezterm/wezterm
Unable to type backslash on mac · Issue #4051 · wezterm/wezterm

To be honest, this area is quite complicated, and while I have worked around it, I'm not sure if these settings are entirely correct.

Adjusting font spacing on Mac similar to iTerm2's v|i

I use UDEV Gothic JPDOC in WezTerm. When this font is displayed on Mac, it looks horizontally cramped. In iTerm2, I adjusted this by changing the setting labeled something like v|i (I wonder what that actually means...?) from 100 to 101.

To do the equivalent in WezTerm, set config.cell_width.

config.cell_width = 1.1 -- This is equivalent to v|i = 101 in iTerm2

It seems possible to achieve the same result by specifying stretch within config.font, but it didn't work in my environment. It might depend on the font.

Reference:
cell_width - Wez's Terminal Emulator
wezterm.font - Wez's Terminal Emulator

License of this article

This document is released under CC BY (Creative Commons Attribution 4.0 International License).