Frequently Asked Questions

Common questions and answers about WezTerm

Answers to frequently asked questions about WezTerm configuration, troubleshooting, and features.

General Questions

What is WezTerm?

WezTerm is a GPU-accelerated cross-platform terminal emulator and multiplexer written in Rust. It runs on Linux, macOS, Windows, and FreeBSD. WezTerm includes features like:

• GPU-accelerated rendering
• Built-in multiplexer (similar to tmux)
• Rich configuration via Lua
• Over 700 built-in color schemes
• Ligature and emoji support
• Hyperlink support
• Split panes and tabs

How do I configure WezTerm?

WezTerm is configured using a Lua file at ~/.wezterm.lua (or ~/.config/wezterm/wezterm.lua).

Basic configuration structure:

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

config.color_scheme = 'Tokyo Night'
config.font_size = 12.0

return config

See the Configuration Examples page for more examples.

Where are WezTerm's config files located?

WezTerm looks for configuration in these locations (in order):

1. ~/.wezterm.lua
2. ~/.config/wezterm/wezterm.lua (Unix/Linux)
3. $XDG_CONFIG_HOME/wezterm/wezterm.lua (if XDG_CONFIG_HOME is set)
4. On Windows: C:\Users\YourName\.wezterm.lua

Log files are stored at:

• Unix: $XDG_RUNTIME_DIR/wezterm
• macOS/Windows: $HOME/.local/share/wezterm

Unicode and Text Rendering

Unicode glyphs render as underscores in my tmux!

This is typically a locale issue. tmux will substitute unicode glyphs with underscores if it believes your environment doesn’t support UTF-8.

Solution:

1. Set your locale correctly:

   export LANG=en_US.UTF-8
   export LC_COLLATE=C  # Optional
   

2. Kill and restart your tmux server:

   tmux kill-server
   

3. Check the TMUX FAQ for additional information.

On macOS with WezTerm version 20200620-160318-e00b076c or newer, LANG is set automatically.

Some glyphs look messed up, why is that?

There are several possible causes:

1. LANG and locale issues

Ensure UTF-8 locale is set:

export LANG=en_US.UTF-8
export LC_COLLATE=C

Check available locales: locale -a

2. Font fallback issues

If your primary font doesn’t contain a glyph, WezTerm tries to find it in fallback fonts. Configure explicit fallback:

config.font = wezterm.font_with_fallback({
  'My Preferred Font',
  'DengXian',  -- For Chinese glyphs
  'Noto Color Emoji',
})

3. Multiple garbage characters

If you see multiple garbage characters instead of one glyph, this is almost always a locale problem. See solution #1 above.

Pasting or entering unicode in zsh looks broken

By default, zsh’s line editor doesn’t support combining character sequences.

Solution:

Add to your ~/.zshrc:

setopt COMBINING_CHARS

Also ensure LANG is configured correctly:

export LANG=en_US.UTF-8

Some (but not all) Emoji don't render properly

This can happen when:

1. Application doesn’t support emoji sequences: Some applications don’t correctly handle multi-codepoint emoji (like skin tone modifiers). The application needs to be updated.

2. Emoji version incompatibility: Different emoji specifications exist. If pasting emoji into zsh REPL breaks, try emitting the same emoji from a script - WezTerm will likely render it correctly.

3. Font doesn’t contain the emoji: Ensure Noto Color Emoji or similar is in your font fallback list (WezTerm includes this by default).

Multiple characters are being rendered as one character (ligatures)

WezTerm supports font ligatures by default. Common examples: != becomes ≠, -> becomes →.

To disable ligatures:

config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }

See the advanced font shaping documentation for more control.

Keyboard and Input

How to troubleshoot keys that don't work or produce weird characters?

Step 1: Enable key event debugging

config.debug_key_events = true

Step 2: Check what bytes are being sent

Run xxd, press the problem key, then Enter, then Ctrl+D:

xxd
# Press key
# Press Enter
# Press Ctrl+D

Step 3: Verify your TERM setting

WezTerm sets TERM=xterm-256color by default. Changing this can break key handling.

Step 4: Check for conflicts

• Look for system-level keyboard utilities intercepting keys
• Check ~/.inputrc for readline settings
• If using tmux, test without tmux first

Step 5: Review the documentation

• Key bindings documentation
• Alt/Option key behavior on macOS

If the issue persists, open an issue with the xxd output and your environment details.

I have 'set convert-meta on' in my ~/.inputrc and characters are broken

The convert-meta readline setting re-encodes latin-1 characters incorrectly in UTF-8 environments.

Example: £ becomes #

Solution: Disable this setting for UTF-8:

# In ~/.inputrc, comment out:
# set convert-meta on

This setting is obsolete in modern UTF-8 terminal environments.

How do I use Alt/Option key on macOS?

The Option key on macOS can either:

1. Send Alt/Meta modifier (terminal behavior)
2. Produce composed characters (macOS default)

WezTerm defaults to terminal behavior. To change:

-- Let left Option key produce composed characters
config.send_composed_key_when_left_alt_is_pressed = true

-- Keep right Option as Alt modifier
config.send_composed_key_when_right_alt_is_pressed = false

Many users prefer keeping right Option for composed characters while left Option acts as Alt.

Features and Capabilities

How do I enable undercurl (curly underlines)?

WezTerm supports curly underlines starting in version 20210314-114017-04b7cedd.

Escape sequences:

CSI 4:3 m  -> Curly underline
CSI 4:4 m  -> Dotted underline
CSI 4:5 m  -> Dashed underline

CSI 58:2::R:G:B m  -> Set underline color (RGB)
CSI 59 m           -> Restore default underline color

Test in your shell:

printf "\x1b[58:2::255:0:0m\x1b[4:3mcurly\x1b[4:4mdotted\x1b[4:5mdashed\x1b[0m\n"

For Neovim:

Install WezTerm terminfo:

tempfile=$(mktemp) && \
  curl -o $tempfile https://raw.githubusercontent.com/wezterm/wezterm/master/termwiz/data/wezterm.terminfo && \
  tic -x -o ~/.terminfo $tempfile && \
  rm $tempfile

# Launch with:
TERM=wezterm nvim

For Vim:

Add to .vimrc:

let &t_Cs = "\e[4:3m"
let &t_Ce = "\e[4:0m"
hi SpellBad guisp=red gui=undercurl guifg=NONE guibg=NONE \
  ctermfg=NONE ctermbg=NONE term=underline cterm=undercurl ctermul=red

On Windows, ConPTY strips curly underline sequences. Use wezterm ssh or multiplexing to bypass ConPTY.

How do I disable ligatures?

Add this to your configuration:

config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }

This disables:

• calt - Contextual alternates
• clig - Contextual ligatures
• liga - Standard ligatures

Can I use custom color schemes?

Yes! WezTerm has several ways to define color schemes:

1. Use a built-in scheme:

config.color_scheme = 'Tokyo Night'

WezTerm includes over 700 built-in color schemes.

2. Define colors inline:

config.colors = {
  foreground = '#c0c0c0',
  background = '#000000',
  cursor_bg = '#52ad70',
  -- ... more colors
}

3. Define multiple schemes:

config.color_schemes = {
  ['My Red Scheme'] = {
    background = 'red',
    foreground = 'white',
  },
}
config.color_scheme = 'My Red Scheme'

4. Load from TOML file:

Place .toml files in ~/.config/wezterm/colors/ with a [colors] section.

Platform-Specific

I'm on macOS and wezterm cannot find things in my PATH

When launched from Finder, WezTerm inherits the minimal macOS default PATH, not your shell’s PATH.

Solution 1: Spawn via shell (recommended):

wezterm.action.SpawnCommandInNewWindow({
  args = {
    os.getenv('SHELL'),
    '-c',
    'nvim ' .. wezterm.shell_quote_arg(wezterm.config_file),
  },
})

zsh users may need to add -l flag to source .zprofile (for Homebrew users) or -i to source .zshrc.

Solution 2: Set PATH in config:

config.set_environment_variables = {
  PATH = wezterm.home_dir .. '/.local/bin:/usr/local/bin:' .. os.getenv('PATH'),
}

Solution 3: Configure launchd (advanced):

sudo launchctl config user path /usr/local/bin:/usr/bin:/bin

Changing launchd’s user path affects all GUI applications and can cause unexpected behavior.

I use X11 or Wayland and my mouse cursor theme doesn't work

XCursor theme resolution is complex and involves multiple configuration sources.

Quick fix:

config.xcursor_theme = 'Adwaita'  -- or your preferred theme

Or via environment:

export XCURSOR_THEME=Adwaita

Debug cursor loading:

WEZTERM_LOG=window::os::x11::cursor=trace wezterm
# Move mouse over window to see resolution attempts

WezTerm tries to find cursors by:

1. Checking xcursor_theme config
2. Reading X11 RESOURCE_MANAGER or XCURSOR_THEME env var
3. Looking in XCURSOR_PATH or default icon directories
4. Falling back to X11 cursor font

If you see the old-school X11 pointer, WezTerm couldn’t find your XCursor theme files.

I use Powershell and cursor keys don't work in other apps

This is a known PowerShell issue. PowerShell enables DECCKM mode and doesn’t restore it when launching external programs.

Result: Arrow keys send ESC O A instead of ESC [ A, which breaks some applications.

This is not a WezTerm issue - it affects all terminal emulators running PowerShell. The PowerShell team needs to fix this.

Workaround: Use a different shell, or restart the affected program in a new terminal session.

Fonts

How do I find out what fonts WezTerm is using?

Use WezTerm’s built-in font debugging:

# Show configured font and fallback
wezterm ls-fonts

# List all available fonts on your system
wezterm ls-fonts --list-system

# See how specific text will render
wezterm ls-fonts --text "Hello 世界 🎉"

# ASCII art rendering preview
wezterm ls-fonts --text "code" --rasterize-ascii

The output shows:

• Which font file is used for each character
• Font weight and style
• Where the font was found (system, config, bundled)

How do I use Nerd Fonts or Powerline symbols?

You don’t need patched fonts! WezTerm includes Nerd Font Symbols in the default fallback.

Just configure your preferred font:

config.font = wezterm.font('JetBrains Mono')

Powerline and icon glyphs will work automatically.

If you want to use a patched Nerd Font anyway, that works too:

config.font = wezterm.font('FiraCode Nerd Font')

What fonts does WezTerm bundle?

WezTerm includes:

• JetBrains Mono - Main default font
• Nerd Font Symbols - Icons and powerline glyphs
• Noto Color Emoji - Emoji support

These are used automatically unless you configure different fonts.

Configuration

How do I reload my configuration?

WezTerm automatically reloads when you save your config file. You can also:

1. Press Ctrl+Shift+R (or Cmd+Shift+R on macOS)
2. Use the command: wezterm cli load-config

If automatic reload isn’t working, check for syntax errors in your config with:

wezterm --config-file ~/.wezterm.lua --help

Can I use multiple configuration files?

Yes! Use Lua’s require to split configuration:

~/.wezterm.lua:

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

-- Load additional config modules
require('keybindings').apply(config)
require('appearance').apply(config)

return config

~/.config/wezterm/keybindings.lua:

local M = {}

function M.apply(config)
  config.leader = { key = 'a', mods = 'CTRL' }
  config.keys = {
    -- ... your keys
  }
end

return M

How do I see all current key bindings?

# Human-readable format
wezterm show-keys

# Lua format (for copying to config)
wezterm show-keys --lua

This shows all effective bindings including defaults and your custom ones.

Troubleshooting

How do I enable debug logging?

WEZTERM_LOG=debug wezterm

For targeted debugging:

# Only debug fonts
WEZTERM_LOG=wezterm_font=debug,info wezterm

# Debug config and fonts
WEZTERM_LOG=config=debug,wezterm_font=debug,info wezterm

Save logs to file:

WEZTERM_LOG=debug wezterm 2>&1 | tee wezterm.log

WezTerm is slow or using too much CPU/GPU

Common causes and solutions:

1. Transparency/opacity:

   config.window_background_opacity = 1.0  -- Disable transparency
   

2. Large background image:

   • Resize image to screen resolution
   • Or disable: remove window_background_image

3. High animation rate:

   config.animation_fps = 10  -- Reduce from 60
   

4. Runaway process in terminal:

   • Check with top or htop
   • Some programs output huge amounts of data

Where do I report bugs or request features?

1. Search existing issues
2. Check the documentation
3. Open a new issue

Include in your report:

• WezTerm version: wezterm --version
• Operating system and version
• Minimal config to reproduce
• Debug logs if relevant: WEZTERM_LOG=debug