Frequently Asked Questions

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):

~/.wezterm.lua
~/.config/wezterm/wezterm.lua (Unix/Linux)
$XDG_CONFIG_HOME/wezterm/wezterm.lua (if XDG_CONFIG_HOME is set)
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:

Set your locale correctly:

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

Kill and restart your tmux server:
```
tmux kill-server
```
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 issuesEnsure UTF-8 locale is set:

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

Check available locales: locale -a2. Font fallback issuesIf 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 charactersIf 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:

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.
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.
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 sentRun xxd, press the problem key, then Enter, then Ctrl+D:

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

Step 3: Verify your TERM settingWezTerm 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:

Send Alt/Meta modifier (terminal behavior)
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:

Checking xcursor_theme config
Reading X11 RESOURCE_MANAGER or XCURSOR_THEME env var
Looking in XCURSOR_PATH or default icon directories
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:

Press Ctrl+Shift+R (or Cmd+Shift+R on macOS)
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:

Transparency/opacity:

config.window_background_opacity = 1.0  -- Disable transparency

Large background image:
- Resize image to screen resolution
- Or disable: remove window_background_image

High animation rate:

config.animation_fps = 10  -- Reduce from 60

Runaway process in terminal:
- Check with top or htop
- Some programs output huge amounts of data

Where do I report bugs or request features?

Search existing issues
Check the documentation
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

Get Started

Core Concepts

Features

Configuration

Guides

Frequently Asked Questions

General Questions

Unicode and Text Rendering

Keyboard and Input

Features and Capabilities

Platform-Specific

Fonts

Configuration

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Configuration

Guides

​General Questions

​Unicode and Text Rendering

​Keyboard and Input

​Features and Capabilities

​Platform-Specific

​Fonts

​Configuration

​Troubleshooting

Build docs developers (and LLMs) love

General Questions

Unicode and Text Rendering

Keyboard and Input

Features and Capabilities

Platform-Specific

Fonts

Configuration

Troubleshooting