> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# Frequently Asked Questions

> Common questions and answers about WezTerm

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

## General Questions

<Accordion title="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
</Accordion>

<Accordion title="How do I configure WezTerm?">
  WezTerm is configured using a Lua file at `~/.wezterm.lua` (or `~/.config/wezterm/wezterm.lua`).

  Basic configuration structure:

  ```lua theme={null}
  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](/guides/configuration-examples) page for more examples.
</Accordion>

<Accordion title="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`
</Accordion>

## Unicode and Text Rendering

<Accordion title="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:
     ```bash theme={null}
     export LANG=en_US.UTF-8
     export LC_COLLATE=C  # Optional
     ```

  2. Kill and restart your tmux server:
     ```bash theme={null}
     tmux kill-server
     ```

  3. Check the [TMUX FAQ](https://github.com/tmux/tmux/wiki/FAQ#how-do-i-use-utf-8) for additional information.

  <Note>
    On macOS with WezTerm version `20200620-160318-e00b076c` or newer, LANG is set automatically.
  </Note>
</Accordion>

<Accordion title="Some glyphs look messed up, why is that?">
  There are several possible causes:

  **1. LANG and locale issues**

  Ensure UTF-8 locale is set:

  ```bash theme={null}
  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:

  ```lua theme={null}
  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.
</Accordion>

<Accordion title="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`:

  ```bash theme={null}
  setopt COMBINING_CHARS
  ```

  Also ensure LANG is configured correctly:

  ```bash theme={null}
  export LANG=en_US.UTF-8
  ```
</Accordion>

<Accordion title="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).
</Accordion>

<Accordion title="Multiple characters are being rendered as one character (ligatures)">
  WezTerm supports font ligatures by default. Common examples: `!=` becomes `≠`, `->` becomes `→`.

  **To disable ligatures:**

  ```lua theme={null}
  config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }
  ```

  See the [advanced font shaping documentation](https://wezfurlong.org/wezterm/config/font-shaping.html) for more control.
</Accordion>

## Keyboard and Input

<Accordion title="How to troubleshoot keys that don't work or produce weird characters?">
  **Step 1: Enable key event debugging**

  ```lua theme={null}
  config.debug_key_events = true
  ```

  **Step 2: Check what bytes are being sent**

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

  ```bash theme={null}
  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](https://wezfurlong.org/wezterm/config/keys.html)
  * Alt/Option key behavior on macOS

  If the issue persists, [open an issue](https://github.com/wezterm/wezterm/issues) with the `xxd` output and your environment details.
</Accordion>

<Accordion title="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:

  ```bash theme={null}
  # In ~/.inputrc, comment out:
  # set convert-meta on
  ```

  This setting is obsolete in modern UTF-8 terminal environments.
</Accordion>

<Accordion title="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:

  ```lua theme={null}
  -- 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.
</Accordion>

## Features and Capabilities

<Accordion title="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:**

  ```bash theme={null}
  printf "\x1b[58:2::255:0:0m\x1b[4:3mcurly\x1b[4:4mdotted\x1b[4:5mdashed\x1b[0m\n"
  ```

  **For Neovim:**

  Install WezTerm terminfo:

  ```bash theme={null}
  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`:

  ```vim theme={null}
  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
  ```

  <Warning>
    On Windows, ConPTY strips curly underline sequences. Use `wezterm ssh` or multiplexing to bypass ConPTY.
  </Warning>
</Accordion>

<Accordion title="How do I disable ligatures?">
  Add this to your configuration:

  ```lua theme={null}
  config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }
  ```

  This disables:

  * `calt` - Contextual alternates
  * `clig` - Contextual ligatures
  * `liga` - Standard ligatures
</Accordion>

<Accordion title="Can I use custom color schemes?">
  Yes! WezTerm has several ways to define color schemes:

  **1. Use a built-in scheme:**

  ```lua theme={null}
  config.color_scheme = 'Tokyo Night'
  ```

  WezTerm includes over 700 built-in color schemes.

  **2. Define colors inline:**

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

  **3. Define multiple schemes:**

  ```lua theme={null}
  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.
</Accordion>

## Platform-Specific

<Accordion title="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):**

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

  <Note>
    zsh users may need to add `-l` flag to source `.zprofile` (for Homebrew users) or `-i` to source `.zshrc`.
  </Note>

  **Solution 2: Set PATH in config:**

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

  **Solution 3: Configure launchd (advanced):**

  ```bash theme={null}
  sudo launchctl config user path /usr/local/bin:/usr/bin:/bin
  ```

  <Warning>
    Changing launchd's user path affects all GUI applications and can cause unexpected behavior.
  </Warning>
</Accordion>

<Accordion title="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:**

  ```lua theme={null}
  config.xcursor_theme = 'Adwaita'  -- or your preferred theme
  ```

  **Or via environment:**

  ```bash theme={null}
  export XCURSOR_THEME=Adwaita
  ```

  **Debug cursor loading:**

  ```bash theme={null}
  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.
</Accordion>

<Accordion title="I use Powershell and cursor keys don't work in other apps">
  This is a [known PowerShell issue](https://github.com/PowerShell/PowerShell/issues/12268). 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.
</Accordion>

## Fonts

<Accordion title="How do I find out what fonts WezTerm is using?">
  Use WezTerm's built-in font debugging:

  ```bash theme={null}
  # 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)
</Accordion>

<Accordion title="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:

  ```lua theme={null}
  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:

  ```lua theme={null}
  config.font = wezterm.font('FiraCode Nerd Font')
  ```
</Accordion>

<Accordion title="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.
</Accordion>

## Configuration

<Accordion title="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:

  ```bash theme={null}
  wezterm --config-file ~/.wezterm.lua --help
  ```
</Accordion>

<Accordion title="Can I use multiple configuration files?">
  Yes! Use Lua's `require` to split configuration:

  **`~/.wezterm.lua`:**

  ```lua theme={null}
  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`:**

  ```lua theme={null}
  local M = {}

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

  return M
  ```
</Accordion>

<Accordion title="How do I see all current key bindings?">
  ```bash theme={null}
  # 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.
</Accordion>

## Troubleshooting

<Accordion title="How do I enable debug logging?">
  ```bash theme={null}
  WEZTERM_LOG=debug wezterm
  ```

  For targeted debugging:

  ```bash theme={null}
  # 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:

  ```bash theme={null}
  WEZTERM_LOG=debug wezterm 2>&1 | tee wezterm.log
  ```
</Accordion>

<Accordion title="WezTerm is slow or using too much CPU/GPU">
  **Common causes and solutions:**

  1. **Transparency/opacity:**
     ```lua theme={null}
     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:**
     ```lua theme={null}
     config.animation_fps = 10  -- Reduce from 60
     ```

  4. **Runaway process in terminal:**
     * Check with `top` or `htop`
     * Some programs output huge amounts of data
</Accordion>

<Accordion title="Where do I report bugs or request features?">
  1. Search [existing issues](https://github.com/wezterm/wezterm/issues)
  2. Check the [documentation](https://wezfurlong.org/wezterm/)
  3. Open a [new issue](https://github.com/wezterm/wezterm/issues/new)

  Include in your report:

  * WezTerm version: `wezterm --version`
  * Operating system and version
  * Minimal config to reproduce
  * Debug logs if relevant: `WEZTERM_LOG=debug`
</Accordion>