<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/faq.md - fork/wezterm @ termwiz-0.23.1</title>
<meta name="description" content="docs/faq.md in fork/wezterm at termwiz-0.23.1.">
<meta property="og:title" content="docs/faq.md - fork/wezterm @ termwiz-0.23.1">
<meta property="og:description" content="docs/faq.md in fork/wezterm at termwiz-0.23.1.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="termwiz-0.23.1" data-tip="7053748e4d899e7fc5e202d6f903b052fc78e759">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/wezterm</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/wezterm</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Wez Furlong</span><span class="commit-message" data-commit="783f8eff3b32b9ffed1bb5d3d3d070713e089f88">docs: show how to set the PATH for Finder on macos</span><span class="snapshot-sha sha" data-commit="783f8eff3b32b9ffed1bb5d3d3d070713e089f88">783f8eff3</span><time datetime="2025-02-08T07:38:46-07:00" title="2025-02-08 07:38:46 -0700">2025-02-08</time></p>
<header class="topbar"><details class="switcher"><summary>termwiz-0.23.1</summary><div class="menu"><strong>branches</strong><a href="/fork/wezterm/ref/main/">main</a><strong>tags</strong><a href="/fork/wezterm/ref/termiz-0.23.1/">termiz-0.23.1</a><a href="/fork/wezterm/ref/termiz-0.23.2/">termiz-0.23.2</a><a href="/fork/wezterm/ref/termiz-0.23.3/">termiz-0.23.3</a><a href="/fork/wezterm/ref/termwiz-0.23.0/">termwiz-0.23.0</a><a class="current" href="/fork/wezterm/ref/termwiz-0.23.1/">termwiz-0.23.1</a><a href="/fork/wezterm/ref/termwiz-0.23.2/">termwiz-0.23.2</a><a href="/fork/wezterm/ref/termwiz-0.23.3/">termwiz-0.23.3</a><a href="/fork/wezterm/ref/vtparse-0.7.0/">vtparse-0.7.0</a><a class="all" href="/fork/wezterm/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/wezterm/">wezterm</a> / <a href="/fork/wezterm/ref/termwiz-0.23.1/tree/docs/">docs</a> / <span class="cur">faq.md</span></nav>
<span class="view-stats"><span>17.6 KiB</span><span>401 lines</span></span><span class="actions"><a class="raw" href="/fork/wezterm/raw/62a265d35be7aa8ec041faed00f36b1e37746ae9/docs/faq.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Frequently Asked Questions</h1>
<h2>Unicode glyphs render as underscores in my tmux!</h2>
<p>This is likely an issue with LANG and locale.  <code>tmux</code> will substitute unicode
glyphs with underscores if it believes that your environment doesn't support
UTF-8.</p>
<p>If you're running on macOS, upgrade to <code>20200620-160318-e00b076c</code> or newer and
WezTerm will automatically set <code>LANG</code> appropriately.</p>
<p>Note that if you change your environment you will likely need to kill and
restart your tmux server before it will take effect.</p>
<p>You probably should also review <a href="https://github.com/tmux/tmux/wiki/FAQ#how-do-i-use-utf-8">this relevant section from the
TMUX FAQ</a>, and
read on for more information about LANG and locale below.</p>
<h2>Some glyphs look messed up, why is that?</h2>
<p>There's a surprisingly amount of work that goes into rendering text,
and if you're connected to a remote host, it may span both systems.
Read on for some gory details!</p>
<h3>LANG and locale</h3>
<p>Terminals operate on byte streams and don't necessarily know anything about the
encoding of the text that you're sending through.  The unix model for this is
that the end user (that's you!) will instruct the applications that you're
running to use a particular locale to interpret the byte stream.</p>
<p>It is common for these environment variables to not be set, or to be set to
invalid values by default!</p>
<p>If you're running on macOS, upgrade to <code>20200620-160318-e00b076c</code> or newer
and WezTerm will automatically set <code>LANG</code> appropriately.</p>
<p>You need to select a unicode locale for best results; for example:</p>
<pre>export LANG=en_US.UTF-8
# You don't strictly need this collation, but most technical people
# probably want C collation for sane results
export LC_COLLATE=C
</pre>
<p>If you have other <code>LC_XXX</code> values in your environment, either remove
them from your environment (if applicable) or adjust them to use a
UTF-8 locale.</p>
<p>You can run <code>locale -a</code> to list the available locales on your system.</p>
<p>You need to make sure that this setting applies both locally and on systems
that you log in to via ssh or the mux connection protocol.</p>
<p>If you're seeing multiple garbage characters in your terminal in place of
what should be a single glyph then you most likely have a problem with your
locale environment variables.</p>
<h3>Pasting or entering unicode in zsh looks broken</h3>
<p>By default, zsh's line editor doesn't support combining character sequences.
Make sure that you have LANG and local configured correctly as shown above,
and then tell zsh to enable combining characters:</p>
<pre>setopt COMBINING_CHARS
</pre>
<p>You'll want to put that into your zshrc so that it is always enabled.</p>
<p>See <a href="https://unix.stackexchange.com/questions/598440/zsh-indic-fonts-support-rendering-issue-which-is-working-fine-on-bash">this stackexchange
question</a>
for more information.</p>
<h3>Fonts and fallback</h3>
<p>If you have configured the use of a font that contains only latin characters
and then try to display a glyph that isn't present in that font (perhaps an
emoji, or perhaps some kanji) then wezterm will try to locate a fallback
font that does contain that glyph.</p>
<p>Wezterm uses freetype and harfbuzz to perform font shaping and rendering in a
cross platform way, and as a consequence, doesn't have access to the system
font fallback selection.  Instead it has a short list of fallback fonts that
are likely to be present on the system and tries to use those.</p>
<p>If you're seeing the unicode replacement character, a question mark or in
the worst cases spaces where a glyph should be, then you have an issue with
font fallback.</p>
<p>You can resolve this by explicitly adding fallback font(s) the have the glyphs
that you need in your <code>.wezterm.lua</code>:</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>wezterm</a-v> = <a-f>require</a-f> <a-s>&#39;wezterm&#39;</a-s>

<a-k>return</a-k> <a-cr>{</a-cr>
  <a-v>font</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-f>font_with_fallback</a-f> <a-cr>{</a-cr>
    <a-s>&#39;My Preferred Font&#39;</a-s><a-p>,</a-p>
    <a-c>-- This font has a broader selection of Chinese glyphs than my preferred font</a-c>
    <a-s>&#39;DengXian&#39;</a-s><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p>See also <a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/fonts.md#troubleshooting-fonts">Troubleshooting Fonts</a>.</p>
<h3>Some (but not all) Emoji don't render properly</h3>
<p>To some extent this issue can manifest in a similar way to the LANG and locale
issue.  There are different versions of the Emoji specifications and the level
of support in different applications can vary.  Emoji can be comprised from a
sequence of codepoints and some combine in interesting ways such as a foot and
a skin tone.  Applications that don't support this correctly may end up
emitting incorrect output.  For example, pasting some emoji into the zsh REPL
confuses its input parser and results in broken emoji output.  However, if you
were to emit that same emoji from a script, wezterm would render it correctly.</p>
<p>If you're seeing this sort of issue, then you may be able to upgrade the
affected application on that system to see if a newer version resolves that
issue.</p>
<h3>Multiple characters being rendered/combined as one character?</h3>
<p><code>wezterm</code> supports <a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/font-shaping.md">advanced font shaping</a>, which,
amongst other things, allows for multiple characters/glyphs to be combined into
one <a href="https://en.wikipedia.org/wiki/Ligature_(writing)">ligature</a>. You may be
experiencing this if, e.g., <code>!=</code> becomes rendered as <code>≠</code> in <code>wezterm</code>.</p>
<p>If you are seeing this kind of "font combining" and wish to disable it, then
this is documented in <a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/font-shaping.md">advanced font shaping options</a>
page.</p>
<h2>How to troubleshoot keys that don't work or produce weird characters!?</h2>
<p>There are a number of layers in input processing that can influence this.</p>
<p>The first thing to note is that <code>wezterm</code> will always and only output <code>UTF-8</code>
encoded text.  Your <code>LANG</code> and locale related environment must be set to
reflect this; there is more information on that above.</p>
<p>If the key in question is produced in combination with Alt/Option then <a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/keys.md">this
section of the docs describes how wezterm processes
Alt/Option</a>, as well as options that influence that behavior.</p>
<p>The next thing to verify is what byte sequences are being produced when you
press keys.  I generally suggest running <code>xxd</code>, pressing the relevant key, then
enter, then CTRL-D.  This should show a hex dump of the the byte sequence.
This step helps to isolate the input from input processing layers in other
applications.</p>
<p>Interactive Unix programs generally depend upon the <code>TERM</code> environment variable
being set appropriately.  <code>wezterm</code> sets this to <code>xterm-256color</code> by default,
because wezterm aims to be compatible with with the settings defined by that
terminfo entry.  Setting TERM to something else can change the byte sequences
that interactive applications expect to see for some keys, effectively
disabling those keys.</p>
<p>On top of this, a number of programs use libraries such as GNU readline
to perform input processing.  That means that settings in your <code>~/.inputrc</code>
may changing the behavior of <code>bash</code>.  Verify any settings in there that
might influence how input is resolved and see the question below
about <code>convert-meta</code>!</p>
<p>If you are using <code>tmux</code> be aware that it introduces its own set of input/output
processing layers that are also sensitive to <code>LANG</code>, <code>TERM</code> and locale and how
they are set in the environment of the tmux server when it was spawned, the
tmux client and inside the processes spawned by tmux.  It is generally best to
troubleshoot input/output weirdness independent of tmux first to minimize the
number of variables!</p>
<p>If after experimenting with your environment and related settings you believe
that wezterm isn't sending the correct input then please <a href="https://github.com/wezterm/wezterm/issues">open an
issue</a> and include the <code>xxd</code> hexdump,
and output from <code>env</code> and any other pertinent information about what you're
trying and why it doesn't match your expectations.</p>
<h2>I have <code>set convert-meta on</code> in my <code>~/.inputrc</code> and latin characters are broken!?</h2>
<p>That setting causes Readline to re-encode latin-1 and other characters
as a different sequence (eg: <code>£</code> will have the high bit stripped and turn
it into <code>#</code>).</p>
<p>You should consider disabling that setting when working with a UTF-8
environment.</p>
<h2>How do I enable undercurl (curly underlines)?</h2>
<p>Starting in version 20210314-114017-04b7cedd, WezTerm has support for colored
and curly underlines.</p>
<p>The relevant escape sequences are:</p>
<pre> CSI 24 m   -&gt; No underline
 CSI 4 m    -&gt; Single underline
 CSI 4:0 m  -&gt; No underline
 CSI 4:1 m  -&gt; Single underline
 CSI 4:2 m  -&gt; Double underline
 CSI 4:3 m  -&gt; Curly underline
 CSI 4:4 m  -&gt; Dotted underline
 CSI 4:5 m  -&gt; Dashed underline

 CSI 58:2::R:G:B m   -&gt; set underline color to specified true color RGB
 CSI 58:5:I m        -&gt; set underline color to palette index I (0-255)
 CSI 59              -&gt; restore underline color to default
</pre>
<p>You can try these out in your shell; this example will print the various
underline styles with a red underline:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>printf</a-pr> <a-s>&quot;\x1b[58:2::255:0:0m\x1b[4:1msingle\x1b[4:2mdouble\x1b[4:3mcurly\x1b[4:4mdotted\x1b[4:5mdashed\x1b[0m\n&quot;</a-s></pre>
<p>To use this in vim, add something like the following to your <code>.vimrc</code>:</p>
<pre class="language-vim"><a-k>let</a-k> <a-o>&amp;</a-o><a-v>t_Cs</a-v> <a-o>=</a-o> <a-s>&quot;\e[4:3m&quot;</a-s>
<a-k>let</a-k> <a-o>&amp;</a-o><a-v>t_Ce</a-v> <a-o>=</a-o> <a-s>&quot;\e[4:0m&quot;</a-s>
<a-k>hi</a-k> <a-t>SpellBad</a-t>   <a-pr>guisp</a-pr><a-o>=</a-o><a-co>red</a-co> <a-pr>gui</a-pr><a-o>=</a-o><a-co>undercurl</a-co> <a-pr>guifg</a-pr><a-o>=</a-o><a-co>NONE</a-co> <a-pr>guibg</a-pr><a-o>=</a-o><a-co>NONE</a-co> \
     <a-k>ctermfg</a-k>=NONE ctermbg=NONE term=underline cterm=undercurl ctermul=red
<a-k>hi</a-k> <a-t>SpellCap</a-t>   <a-pr>guisp</a-pr><a-o>=</a-o><a-co>yellow</a-co> <a-pr>gui</a-pr><a-o>=</a-o><a-co>undercurl</a-co> <a-pr>guifg</a-pr><a-o>=</a-o><a-co>NONE</a-co> <a-pr>guibg</a-pr><a-o>=</a-o><a-co>NONE</a-co> \
     <a-k>ctermfg</a-k>=NONE ctermbg=NONE term=underline cterm=undercurl ctermul=yellow</pre>
<p>If you are a neovim user then you will need to install a terminfo file that
tells neovim about this support.</p>
<p>You may wish to try these steps to install a copy of a <code>wezterm</code> terminfo file;
this will compile a copy of the terminfo and install it into your <code>~/.terminfo</code>
directory:</p>
<pre class="language-bash"><a-pr>tempfile</a-pr>=<a-eb>$(</a-eb><a-f>mktemp</a-f><a-eb>)</a-eb> \
  <a-o>&amp;&amp;</a-o> <a-f>curl</a-f> <a-co>-o</a-co> <a-o>$</a-o><a-pr>tempfile</a-pr> https://raw.githubusercontent.com/wezterm/wezterm/master/termwiz/data/wezterm.terminfo \
  <a-o>&amp;&amp;</a-o> <a-f>tic</a-f> <a-co>-x</a-co> <a-co>-o</a-co> ~/.terminfo <a-o>$</a-o><a-pr>tempfile</a-pr> \
  <a-o>&amp;&amp;</a-o> <a-f>rm</a-f> <a-o>$</a-o><a-pr>tempfile</a-pr></pre>
<p>With that in place, you can then start neovim like this, and it should enable
undercurl:</p>
<pre class="language-bash"><a-f>env</a-f> TERM=wezterm nvim</pre>
<p>Note: on Windows, the ConPTY layer strips out the curly underline escape
sequences.  If you're missing this feature in your WSL instance, you will need
to use either <code>wezterm ssh</code> or
<a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/multiplexing.md#connecting-into-windows-subsystem-for-linux">multiplexing</a>
to bypass ConPTY.</p>
<h2>I use Powershell for my shell, and I have problems with cursor keys in other apps</h2>
<p>Powershell has <a href="https://github.com/PowerShell/PowerShell/issues/12268">an open issue</a> where it
enables the <a href="https://vt100.net/docs/vt510-rm/DECCKM">DECCKM</a> mode of the terminal and does
not restore it prior to launching external commands.</p>
<p>The consequence of enabling DECCKM is that cursor keys switch from being
reported as eg: <code>ESC [ A</code> (for UpArrow) to <code>ESC O A</code>.</p>
<p>Some applications don't know how to deal with this and as a consequence, won't
see the cursor keys.</p>
<p>This is not an issue in WezTerm; the same issue manifests in any terminal
emulator that runs powershell.</p>
<h2>I use X11 or Wayland and my mouse cursor theme doesn't seem to work</h2>
<p><strong>What is this old school X11 mouse pointer thing?!</strong></p>
<p>Resolving the mouse cursor style in these environments is surprisingly complicated:</p>
<ul>
<li>
<p>Determine the XCursor theme:</p>
<ol>
<li>is <code>xcursor_theme</code> set in the wezterm configuration?</li>
<li>X11: Does the root window publish the <code>XCursor.theme</code> resource? (You can manually run <code>xprop -root | grep RESOURCE_MANAGER | perl -pe 's/\\n/\n/g'  | grep -i cursor</code> to check for yourself)</li>
<li>Wayland: from the <code>XCURSOR_THEME</code> environment variable</li>
<li>Otherwise, assume <code>default</code></li>
</ol>
</li>
<li>
<p>Determine the icon path:</p>
<ol>
<li>Is <code>XCURSOR_PATH</code> set in the environment? If so, use that.</li>
<li>Construct a default path derived from some hard coded locations and the contents of the <code>XDG_DATA_HOME</code> and <code>XDG_DATA_DIRS</code> environment variables.</li>
</ol>
</li>
</ul>
<p>When a cursor is needed, the XCursor theme is tried first:</p>
<ol>
<li>X11: the X Server must support the <code>RENDER</code> extension, version 0.5 or later, and support ARGB32</li>
<li>A set of candidate cursor names is produced for the desired cursor</li>
<li>For each location in the icon path, the XCursor theme and the candidate name are combined to produce a candidate file name</li>
<li>If the file exists, then wezterm will try to load it</li>
</ol>
<p>If no XCursor was found, wezterm will fall back to using the default X11 cursor
font provided by the system.</p>
<p>{{since('20220624-141144-bd1b7c5d')}}</p>
<p>When troubleshooting xcursor issues, you can enable tracing by turning on the log level shown
below, and then moving the mouse over the wezterm window:</p>
<pre>; WEZTERM_LOG=window::os::x11::cursor=trace wezterm
07:34:40.001  TRACE  window::os::x11::cursor &gt; Constructing default icon path because $XCURSOR_PATH is not set
07:34:40.001  TRACE  window::os::x11::cursor &gt; Using ~/.local/share because $XDG_DATA_HOME is not set
07:34:40.001  TRACE  window::os::x11::cursor &gt; Using $XDG_DATA_DIRS location &quot;/home/wez/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share/:/usr/share/&quot;
07:34:40.001  TRACE  window::os::x11::cursor &gt; icon_path is [&quot;/home/wez/.local/share/icons&quot;, &quot;/home/wez/.icons&quot;, &quot;/home/wez/.local/share/flatpak/exports/share/icons&quot;, &quot;/var/lib/flatpak/exports/share/icons&quot;, &quot;/usr/local/share/icons&quot;, &quot;/usr/share/icons&quot;, &quot;/usr/share/pixmaps&quot;, &quot;/home/wez/.cursors&quot;, &quot;/usr/share/cursors/xorg-x11&quot;, &quot;/usr/X11R6/lib/X11/icons&quot;]
07:34:41.838  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/home/wez/.local/share/icons/Adwaita/cursors/xterm&quot;
07:34:41.838  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/home/wez/.icons/Adwaita/cursors/xterm&quot;
07:34:41.839  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/home/wez/.local/share/flatpak/exports/share/icons/Adwaita/cursors/xterm&quot;
07:34:41.839  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/var/lib/flatpak/exports/share/icons/Adwaita/cursors/xterm&quot;
07:34:41.839  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/usr/local/share/icons/Adwaita/cursors/xterm&quot;
07:34:41.839  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/usr/share/icons/Adwaita/cursors/xterm&quot;
07:34:41.839  TRACE  window::os::x11::cursor &gt; Some(Text) resolved to &quot;/usr/share/icons/Adwaita/cursors/xterm&quot;
07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.local/share/icons/Adwaita/cursors/top_left_arrow&quot;
07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.local/share/icons/Adwaita/cursors/left_ptr&quot;
07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.icons/Adwaita/cursors/top_left_arrow&quot;
07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.icons/Adwaita/cursors/left_ptr&quot;
07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.local/share/flatpak/exports/share/icons/Adwaita/cursors/top_left_arrow&quot;
07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.local/share/flatpak/exports/share/icons/Adwaita/cursors/left_ptr&quot;
07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/var/lib/flatpak/exports/share/icons/Adwaita/cursors/top_left_arrow&quot;
07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/var/lib/flatpak/exports/share/icons/Adwaita/cursors/left_ptr&quot;
07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/usr/local/share/icons/Adwaita/cursors/top_left_arrow&quot;
07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/usr/local/share/icons/Adwaita/cursors/left_ptr&quot;
07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/usr/share/icons/Adwaita/cursors/top_left_arrow&quot;
07:34:42.917  TRACE  window::os::x11::cursor &gt; Some(Arrow) resolved to &quot;/usr/share/icons/Adwaita/cursors/top_left_arrow&quot;
</pre>
<h2>I'm on macOS and wezterm cannot find things in my PATH</h2>
<p>On macOS, wezterm is typically launched directly by the Finder process and inherits
the default and fairly sparse macOS PATH environment.  That's sufficient for launching
your shell, which is then responsible for processing your rcfiles and setting up your
PATH.</p>
<p>However, if you want wezterm to directly spawn some other utility that isn't in that
basic PATH, wezterm will report that it cannot find it.</p>
<p>Probably the easiest to maintain solution is to change something like:</p>
<pre class="language-lua"><a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v><a-p>.</a-p><a-f>SpawnCommandInNewWindow</a-f> <a-cr>{</a-cr>
  <a-v>args</a-v> = <a-cr>{</a-cr> <a-s>&#39;nvim&#39;</a-s><a-p>,</a-p> <a-v>wezterm</a-v><a-p>.</a-p><a-v>config_file</a-v> <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p>so that it explicitly spawns the command using your shell:</p>
<pre class="language-lua"><a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v><a-p>.</a-p><a-f>SpawnCommandInNewWindow</a-f> <a-cr>{</a-cr>
  <a-v>args</a-v> = <a-cr>{</a-cr>
    <a-v>os</a-v><a-p>.</a-p><a-f>getenv</a-f> <a-s>&#39;SHELL&#39;</a-s><a-p>,</a-p>
    <a-s>&#39;-c&#39;</a-s><a-p>,</a-p>
    <a-s>&#39;nvim &#39;</a-s> <a-o>..</a-o> <a-v>wezterm</a-v><a-p>.</a-p><a-f>shell_quote_arg</a-f><a-p>(</a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>config_file</a-v><a-p>),</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p>another option is to explicitly use the full path to the program on your system,
something like:</p>
<pre class="language-lua"><a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v><a-p>.</a-p><a-f>SpawnCommandInNewWindow</a-f> <a-cr>{</a-cr>
  <a-v>args</a-v> = <a-cr>{</a-cr>
    <a-v>wezterm</a-v><a-p>.</a-p><a-v>home_dir</a-v> <a-o>..</a-o> <a-s>&#39;/.local/bob/nvim-bin/nvim&#39;</a-s><a-p>,</a-p>
    <a-v>wezterm</a-v><a-p>.</a-p><a-v>config_file</a-v><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p>and another other option is to explicitly set the PATH up:</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>set_environment_variables</a-v> = <a-cr>{</a-cr>
  <a-c>-- prepend the path to your utility and include the rest of the PATH</a-c>
  <a-v>PATH</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-v>home_dir</a-v> <a-o>..</a-o> <a-s>&#39;/.local/bob/nvim-bin:&#39;</a-s> <a-o>..</a-o> <a-v>os</a-v><a-p>.</a-p><a-f>getenv</a-f> <a-s>&#39;PATH&#39;</a-s><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p>and yet another option is to configure launchd to use a more expansive
PATH for all processes in your user session using <code>launchctl config user path</code>
doing something like this:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>sudo</a-pr> launchctl config user path <a-o>&lt;</a-o>my path setting<a-o>&gt;</a-o></pre>
<p>!!! warning
Take care with setting the user path using this technique, as if you change
that path in a way that system-provided utilities are lower priority than
alternative software that you have installed, you may unexpectedly change
the overall system behavior.</p>
<p>See also:</p>
<ul>
<li><a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/lua/config/set_environment_variables.md">set_environment_variables</a></li>
<li><a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/lua/SpawnCommand.md">SpawnCommand</a></li>
<li><a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/lua/wezterm/config_file.md">wezterm.config_file</a></li>
<li><a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/lua/wezterm/shell_quote_arg.md">wezterm.shell_quote_arg</a></li>
<li><a href="https://apple.stackexchange.com/q/51677/166425">how to set the PATH for Finder-launched applications</a></li>
<li><a href="https://stackoverflow.com/q/51636338/149111">what does launchctl config user path do?</a></li>
</ul>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>Frequently Asked Questions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text"><a-p>##</a-p> <a-tt>Unicode glyphs render as underscores in my tmux!</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">This is likely an issue with LANG and locale.  `tmux` will substitute unicode</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">glyphs with underscores if it believes that your environment doesn&#39;t support</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">UTF-8.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">If you&#39;re running on macOS, upgrade to `20200620-160318-e00b076c` or newer and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">WezTerm will automatically set `LANG` appropriately.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">Note that if you change your environment you will likely need to kill and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">restart your tmux server before it will take effect.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">You probably should also review [this relevant section from the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text">TMUX FAQ](https://github.com/tmux/tmux/wiki/FAQ#how-do-i-use-utf-8), and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">read on for more information about LANG and locale below.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>##</a-p> <a-tt>Some glyphs look messed up, why is that?</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">There&#39;s a surprisingly amount of work that goes into rendering text,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">and if you&#39;re connected to a remote host, it may span both systems.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">Read on for some gory details!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>###</a-p> <a-tt>LANG and locale</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">Terminals operate on byte streams and don&#39;t necessarily know anything about the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">encoding of the text that you&#39;re sending through.  The unix model for this is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">that the end user (that&#39;s you!) will instruct the applications that you&#39;re</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">running to use a particular locale to interpret the byte stream.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">It is common for these environment variables to not be set, or to be set to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">invalid values by default!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">If you&#39;re running on macOS, upgrade to `20200620-160318-e00b076c` or newer</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">and WezTerm will automatically set `LANG` appropriately.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">You need to select a unicode locale for best results; for example:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>export LANG=en_US.UTF-8</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p># You don&#39;t strictly need this collation, but most technical people</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p># probably want C collation for sane results</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>export LC_COLLATE=C</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>If you have other `LC_XXX` values in your environment, either remove</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>them from your environment (if applicable) or adjust them to use a</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>UTF-8 locale.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>You can run `locale -a` to list the available locales on your system.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>You need to make sure that this setting applies both locally and on systems</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"><a-p>that you log in to via ssh or the mux connection protocol.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>If you&#39;re seeing multiple garbage characters in your terminal in place of</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>what should be a single glyph then you most likely have a problem with your</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>locale environment variables.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>### </a-p><a-tt>Pasting or entering unicode in zsh looks broken</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>By default, zsh&#39;s line editor doesn&#39;t support combining character sequences.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>Make sure that you have LANG and local configured correctly as shown above,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>and then tell zsh to enable combining characters:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>setopt COMBINING_CHARS</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>You&#39;ll want to put that into your zshrc so that it is always enabled.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"><a-p>See [this stackexchange</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-p>question](https://unix.stackexchange.com/questions/598440/zsh-indic-fonts-support-rendering-issue-which-is-working-fine-on-bash)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"><a-p>for more information.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-p>### </a-p><a-tt>Fonts and fallback</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p>If you have configured the use of a font that contains only latin characters</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"><a-p>and then try to display a glyph that isn&#39;t present in that font (perhaps an</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"><a-p>emoji, or perhaps some kanji) then wezterm will try to locate a fallback</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"><a-p>font that does contain that glyph.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"><a-p>Wezterm uses freetype and harfbuzz to perform font shaping and rendering in a</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"><a-p>cross platform way, and as a consequence, doesn&#39;t have access to the system</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"><a-p>font fallback selection.  Instead it has a short list of fallback fonts that</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"><a-p>are likely to be present on the system and tries to use those.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"><a-p>If you&#39;re seeing the unicode replacement character, a question mark or in</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"><a-p>the worst cases spaces where a glyph should be, then you have an issue with</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"><a-p>font fallback.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"><a-p>You can resolve this by explicitly adding fallback font(s) the have the glyphs</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"><a-p>that you need in your `.wezterm.lua`:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>local </a-p><a-v>wezterm</a-v><a-p> = </a-p><a-f>require</a-f><a-p> </a-p><a-s>&#39;wezterm&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"><a-p>return </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"><a-p>  </a-p><a-v>font</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>font_with_fallback</a-f><a-p> </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"><a-p>    </a-p><a-s>&#39;My Preferred Font&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"><a-p>    </a-p><a-c>-- This font has a broader selection of Chinese glyphs than my preferred font</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text"><a-p>    </a-p><a-s>&#39;DengXian&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"><a-p>See also [Troubleshooting Fonts](config/fonts.md#troubleshooting-fonts).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text"><a-p>### </a-p><a-tt>Some (but not all) Emoji don&#39;t render properly</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"><a-p>To some extent this issue can manifest in a similar way to the LANG and locale</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"><a-p>issue.  There are different versions of the Emoji specifications and the level</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"><a-p>of support in different applications can vary.  Emoji can be comprised from a</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"><a-p>sequence of codepoints and some combine in interesting ways such as a foot and</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text"><a-p>a skin tone.  Applications that don&#39;t support this correctly may end up</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"><a-p>emitting incorrect output.  For example, pasting some emoji into the zsh REPL</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text"><a-p>confuses its input parser and results in broken emoji output.  However, if you</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"><a-p>were to emit that same emoji from a script, wezterm would render it correctly.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"><a-p>If you&#39;re seeing this sort of issue, then you may be able to upgrade the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"><a-p>affected application on that system to see if a newer version resolves that</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"><a-p>issue.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"><a-p>### </a-p><a-tt>Multiple characters being rendered/combined as one character?</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"><a-p>`wezterm` supports [advanced font shaping](config/font-shaping.md), which,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"><a-p>amongst other things, allows for multiple characters/glyphs to be combined into</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text"><a-p>one [ligature](https://en.wikipedia.org/wiki/Ligature_(writing)). You may be</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text"><a-p>experiencing this if, e.g., `!=` becomes rendered as `≠` in `wezterm`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"><a-p>If you are seeing this kind of &quot;font combining&quot; and wish to disable it, then</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"><a-p>this is documented in [advanced font shaping options](config/font-shaping.md)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text"><a-p>page.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text"><a-p>## </a-p><a-tt>How to troubleshoot keys that don&#39;t work or produce weird characters!?</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text"><a-p>There are a number of layers in input processing that can influence this.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text"><a-p>The first thing to note is that `wezterm` will always and only output `UTF-8`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"><a-p>encoded text.  Your `LANG` and locale related environment must be set to</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text"><a-p>reflect this; there is more information on that above.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text"><a-p>If the key in question is produced in combination with Alt/Option then [this</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text"><a-p>section of the docs describes how wezterm processes</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text"><a-p>Alt/Option](config/keys.md), as well as options that influence that behavior.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text"><a-p>The next thing to verify is what byte sequences are being produced when you</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"><a-p>press keys.  I generally suggest running `xxd`, pressing the relevant key, then</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"><a-p>enter, then CTRL-D.  This should show a hex dump of the the byte sequence.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text"><a-p>This step helps to isolate the input from input processing layers in other</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text"><a-p>applications.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text"><a-p>Interactive Unix programs generally depend upon the `TERM` environment variable</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"><a-p>being set appropriately.  `wezterm` sets this to `xterm-256color` by default,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text"><a-p>because wezterm aims to be compatible with with the settings defined by that</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"><a-p>terminfo entry.  Setting TERM to something else can change the byte sequences</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text"><a-p>that interactive applications expect to see for some keys, effectively</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text"><a-p>disabling those keys.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"><a-p>On top of this, a number of programs use libraries such as GNU readline</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text"><a-p>to perform input processing.  That means that settings in your `~/.inputrc`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"><a-p>may changing the behavior of `bash`.  Verify any settings in there that</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text"><a-p>might influence how input is resolved and see the question below</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text"><a-p>about `convert-meta`!</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text"><a-p>If you are using `tmux` be aware that it introduces its own set of input/output</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text"><a-p>processing layers that are also sensitive to `LANG`, `TERM` and locale and how</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text"><a-p>they are set in the environment of the tmux server when it was spawned, the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text"><a-p>tmux client and inside the processes spawned by tmux.  It is generally best to</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text"><a-p>troubleshoot input/output weirdness independent of tmux first to minimize the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text"><a-p>number of variables!</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text"><a-p>If after experimenting with your environment and related settings you believe</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"><a-p>that wezterm isn&#39;t sending the correct input then please [open an</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text"><a-p>issue](https://github.com/wezterm/wezterm/issues) and include the `xxd` hexdump,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text"><a-p>and output from `env` and any other pertinent information about what you&#39;re</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text"><a-p>trying and why it doesn&#39;t match your expectations.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text"><a-p>## </a-p><a-tt>I have `set convert-meta on` in my `~/.inputrc` and latin characters are broken!?</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text"><a-p>That setting causes Readline to re-encode latin-1 and other characters</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"><a-p>as a different sequence (eg: `£` will have the high bit stripped and turn</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text"><a-p>it into `#`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"><a-p>You should consider disabling that setting when working with a UTF-8</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text"><a-p>environment.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"><a-p>## </a-p><a-tt>How do I enable undercurl (curly underlines)?</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text"><a-p>Starting in version 20210314-114017-04b7cedd, WezTerm has support for colored</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text"><a-p>and curly underlines.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text"><a-p>The relevant escape sequences are:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text"><a-p> CSI 24 m   -&gt; No underline</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text"><a-p> CSI 4 m    -&gt; Single underline</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text"><a-p> CSI 4:0 m  -&gt; No underline</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text"><a-p> CSI 4:1 m  -&gt; Single underline</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text"><a-p> CSI 4:2 m  -&gt; Double underline</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text"><a-p> CSI 4:3 m  -&gt; Curly underline</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text"><a-p> CSI 4:4 m  -&gt; Dotted underline</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text"><a-p> CSI 4:5 m  -&gt; Dashed underline</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text"><a-p> CSI 58:2::R:G:B m   -&gt; set underline color to specified true color RGB</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text"><a-p> CSI 58:5:I m        -&gt; set underline color to palette index I (0-255)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text"><a-p> CSI 59              -&gt; restore underline color to default</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L208" href="#L208">208</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L209" href="#L209">209</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L210" href="#L210">210</a><span class="code-text"><a-p>You can try these out in your shell; this example will print the various</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L211" href="#L211">211</a><span class="code-text"><a-p>underline styles with a red underline:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L212" href="#L212">212</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L213" href="#L213">213</a><span class="code-text"><a-p>```</a-p><a-tl>bash</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L214" href="#L214">214</a><span class="code-text"><a-p>$ </a-p><a-pr>printf</a-pr><a-p> </a-p><a-s>&quot;\x1b[58:2::255:0:0m\x1b[4:1msingle\x1b[4:2mdouble\x1b[4:3mcurly\x1b[4:4mdotted\x1b[4:5mdashed\x1b[0m\n&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L215" href="#L215">215</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L216" href="#L216">216</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L217" href="#L217">217</a><span class="code-text"><a-p>To use this in vim, add something like the following to your `.vimrc`:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L218" href="#L218">218</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L219" href="#L219">219</a><span class="code-text"><a-p>```</a-p><a-tl>vim</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L220" href="#L220">220</a><span class="code-text"><a-p>let </a-p><a-o>&amp;</a-o><a-v>t_Cs</a-v><a-p> </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;\e[4:3m&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L221" href="#L221">221</a><span class="code-text"><a-p>let </a-p><a-o>&amp;</a-o><a-v>t_Ce</a-v><a-p> </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;\e[4:0m&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L222" href="#L222">222</a><span class="code-text"><a-p>hi </a-p><a-t>SpellBad</a-t><a-p>   </a-p><a-pr>guisp</a-pr><a-o>=</a-o><a-co>red</a-co><a-p> </a-p><a-pr>gui</a-pr><a-o>=</a-o><a-co>undercurl</a-co><a-p> </a-p><a-pr>guifg</a-pr><a-o>=</a-o><a-co>NONE</a-co><a-p> </a-p><a-pr>guibg</a-pr><a-o>=</a-o><a-co>NONE</a-co><a-p> \</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text"><a-p>     </a-p><a-k>ctermfg</a-k><a-p>=NONE ctermbg=NONE term=underline cterm=undercurl ctermul=red</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L224" href="#L224">224</a><span class="code-text"><a-p>hi </a-p><a-t>SpellCap</a-t><a-p>   </a-p><a-pr>guisp</a-pr><a-o>=</a-o><a-co>yellow</a-co><a-p> </a-p><a-pr>gui</a-pr><a-o>=</a-o><a-co>undercurl</a-co><a-p> </a-p><a-pr>guifg</a-pr><a-o>=</a-o><a-co>NONE</a-co><a-p> </a-p><a-pr>guibg</a-pr><a-o>=</a-o><a-co>NONE</a-co><a-p> \</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L225" href="#L225">225</a><span class="code-text"><a-p>     </a-p><a-k>ctermfg</a-k><a-p>=NONE ctermbg=NONE term=underline cterm=undercurl ctermul=yellow</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L226" href="#L226">226</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L227" href="#L227">227</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L228" href="#L228">228</a><span class="code-text"><a-p>If you are a neovim user then you will need to install a terminfo file that</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L229" href="#L229">229</a><span class="code-text"><a-p>tells neovim about this support.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L230" href="#L230">230</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L231" href="#L231">231</a><span class="code-text"><a-p>You may wish to try these steps to install a copy of a `wezterm` terminfo file;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L232" href="#L232">232</a><span class="code-text"><a-p>this will compile a copy of the terminfo and install it into your `~/.terminfo`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L233" href="#L233">233</a><span class="code-text"><a-p>directory:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L234" href="#L234">234</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L235" href="#L235">235</a><span class="code-text"><a-p>```</a-p><a-tl>bash</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L236" href="#L236">236</a><span class="code-text"><a-p>tempfile=</a-p><a-eb>$(</a-eb><a-f>mktemp</a-f><a-eb>)</a-eb><a-p> \</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L237" href="#L237">237</a><span class="code-text"><a-p>  </a-p><a-o>&amp;&amp;</a-o><a-p> </a-p><a-f>curl</a-f><a-p> </a-p><a-co>-o</a-co><a-p> </a-p><a-o>$</a-o><a-pr>tempfile</a-pr><a-p> https://raw.githubusercontent.com/wezterm/wezterm/master/termwiz/data/wezterm.terminfo \</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L238" href="#L238">238</a><span class="code-text"><a-p>  </a-p><a-o>&amp;&amp;</a-o><a-p> </a-p><a-f>tic</a-f><a-p> </a-p><a-co>-x</a-co><a-p> </a-p><a-co>-o</a-co><a-p> ~/.terminfo </a-p><a-o>$</a-o><a-pr>tempfile</a-pr><a-p> \</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L239" href="#L239">239</a><span class="code-text"><a-p>  </a-p><a-o>&amp;&amp;</a-o><a-p> </a-p><a-f>rm</a-f><a-p> </a-p><a-o>$</a-o><a-pr>tempfile</a-pr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L240" href="#L240">240</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L241" href="#L241">241</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L242" href="#L242">242</a><span class="code-text"><a-p>With that in place, you can then start neovim like this, and it should enable</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L243" href="#L243">243</a><span class="code-text"><a-p>undercurl:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L244" href="#L244">244</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L245" href="#L245">245</a><span class="code-text"><a-p>```</a-p><a-tl>bash</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L246" href="#L246">246</a><span class="code-text"><a-p>env TERM=wezterm nvim</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L247" href="#L247">247</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L248" href="#L248">248</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L249" href="#L249">249</a><span class="code-text"><a-p>Note: on Windows, the ConPTY layer strips out the curly underline escape</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L250" href="#L250">250</a><span class="code-text"><a-p>sequences.  If you&#39;re missing this feature in your WSL instance, you will need</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L251" href="#L251">251</a><span class="code-text"><a-p>to use either `wezterm ssh` or</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L252" href="#L252">252</a><span class="code-text"><a-p>[multiplexing](multiplexing.md#connecting-into-windows-subsystem-for-linux)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L253" href="#L253">253</a><span class="code-text"><a-p>to bypass ConPTY.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L254" href="#L254">254</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L255" href="#L255">255</a><span class="code-text"><a-p>## </a-p><a-tt>I use Powershell for my shell, and I have problems with cursor keys in other apps</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L256" href="#L256">256</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L257" href="#L257">257</a><span class="code-text"><a-p>Powershell has [an open issue](https://github.com/PowerShell/PowerShell/issues/12268) where it</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L258" href="#L258">258</a><span class="code-text"><a-p>enables the [DECCKM](https://vt100.net/docs/vt510-rm/DECCKM) mode of the terminal and does</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L259" href="#L259">259</a><span class="code-text"><a-p>not restore it prior to launching external commands.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L260" href="#L260">260</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L261" href="#L261">261</a><span class="code-text"><a-p>The consequence of enabling DECCKM is that cursor keys switch from being</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L262" href="#L262">262</a><span class="code-text"><a-p>reported as eg: `ESC [ A` (for UpArrow) to `ESC O A`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L263" href="#L263">263</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L264" href="#L264">264</a><span class="code-text"><a-p>Some applications don&#39;t know how to deal with this and as a consequence, won&#39;t</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L265" href="#L265">265</a><span class="code-text"><a-p>see the cursor keys.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L266" href="#L266">266</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L267" href="#L267">267</a><span class="code-text"><a-p>This is not an issue in WezTerm; the same issue manifests in any terminal</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L268" href="#L268">268</a><span class="code-text"><a-p>emulator that runs powershell.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L269" href="#L269">269</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L270" href="#L270">270</a><span class="code-text"><a-p>## </a-p><a-tt>I use X11 or Wayland and my mouse cursor theme doesn&#39;t seem to work</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L271" href="#L271">271</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L272" href="#L272">272</a><span class="code-text"><a-p>**What is this old school X11 mouse pointer thing?!**</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L273" href="#L273">273</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L274" href="#L274">274</a><span class="code-text"><a-p>Resolving the mouse cursor style in these environments is surprisingly complicated:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L275" href="#L275">275</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L276" href="#L276">276</a><span class="code-text"><a-p>* Determine the XCursor theme:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L277" href="#L277">277</a><span class="code-text"><a-p>  1. is `xcursor_theme` set in the wezterm configuration?</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L278" href="#L278">278</a><span class="code-text"><a-p>  2. X11: Does the root window publish the `XCursor.theme` resource? (You can manually run `xprop -root | grep RESOURCE_MANAGER | perl -pe &#39;s/\\n/\n/g&#39;  | grep -i cursor` to check for yourself)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L279" href="#L279">279</a><span class="code-text"><a-p>  3. Wayland: from the `XCURSOR_THEME` environment variable</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L280" href="#L280">280</a><span class="code-text"><a-p>  4. Otherwise, assume `default`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L281" href="#L281">281</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L282" href="#L282">282</a><span class="code-text"><a-p>* Determine the icon path:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L283" href="#L283">283</a><span class="code-text"><a-p>  1. Is `XCURSOR_PATH` set in the environment? If so, use that.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L284" href="#L284">284</a><span class="code-text"><a-p>  2. Construct a default path derived from some hard coded locations and the contents of the `XDG_DATA_HOME` and `XDG_DATA_DIRS` environment variables.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L285" href="#L285">285</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L286" href="#L286">286</a><span class="code-text"><a-p>When a cursor is needed, the XCursor theme is tried first:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L287" href="#L287">287</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L288" href="#L288">288</a><span class="code-text"><a-p>1. X11: the X Server must support the `RENDER` extension, version 0.5 or later, and support ARGB32</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L289" href="#L289">289</a><span class="code-text"><a-p>2. A set of candidate cursor names is produced for the desired cursor</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L290" href="#L290">290</a><span class="code-text"><a-p>3. For each location in the icon path, the XCursor theme and the candidate name are combined to produce a candidate file name</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L291" href="#L291">291</a><span class="code-text"><a-p>4. If the file exists, then wezterm will try to load it</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L292" href="#L292">292</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L293" href="#L293">293</a><span class="code-text"><a-p>If no XCursor was found, wezterm will fall back to using the default X11 cursor</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L294" href="#L294">294</a><span class="code-text"><a-p>font provided by the system.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L295" href="#L295">295</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L296" href="#L296">296</a><span class="code-text"><a-p>{{since(&#39;20220624-141144-bd1b7c5d&#39;)}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L297" href="#L297">297</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L298" href="#L298">298</a><span class="code-text"><a-p>When troubleshooting xcursor issues, you can enable tracing by turning on the log level shown</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L299" href="#L299">299</a><span class="code-text"><a-p>below, and then moving the mouse over the wezterm window:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L300" href="#L300">300</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L301" href="#L301">301</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L302" href="#L302">302</a><span class="code-text"><a-p>; WEZTERM_LOG=window::os::x11::cursor=trace wezterm</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L303" href="#L303">303</a><span class="code-text"><a-p>07:34:40.001  TRACE  window::os::x11::cursor &gt; Constructing default icon path because $XCURSOR_PATH is not set</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L304" href="#L304">304</a><span class="code-text"><a-p>07:34:40.001  TRACE  window::os::x11::cursor &gt; Using ~/.local/share because $XDG_DATA_HOME is not set</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L305" href="#L305">305</a><span class="code-text"><a-p>07:34:40.001  TRACE  window::os::x11::cursor &gt; Using $XDG_DATA_DIRS location &quot;/home/wez/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share/:/usr/share/&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L306" href="#L306">306</a><span class="code-text"><a-p>07:34:40.001  TRACE  window::os::x11::cursor &gt; icon_path is [&quot;/home/wez/.local/share/icons&quot;, &quot;/home/wez/.icons&quot;, &quot;/home/wez/.local/share/flatpak/exports/share/icons&quot;, &quot;/var/lib/flatpak/exports/share/icons&quot;, &quot;/usr/local/share/icons&quot;, &quot;/usr/share/icons&quot;, &quot;/usr/share/pixmaps&quot;, &quot;/home/wez/.cursors&quot;, &quot;/usr/share/cursors/xorg-x11&quot;, &quot;/usr/X11R6/lib/X11/icons&quot;]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L307" href="#L307">307</a><span class="code-text"><a-p>07:34:41.838  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/home/wez/.local/share/icons/Adwaita/cursors/xterm&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L308" href="#L308">308</a><span class="code-text"><a-p>07:34:41.838  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/home/wez/.icons/Adwaita/cursors/xterm&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L309" href="#L309">309</a><span class="code-text"><a-p>07:34:41.839  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/home/wez/.local/share/flatpak/exports/share/icons/Adwaita/cursors/xterm&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L310" href="#L310">310</a><span class="code-text"><a-p>07:34:41.839  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/var/lib/flatpak/exports/share/icons/Adwaita/cursors/xterm&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L311" href="#L311">311</a><span class="code-text"><a-p>07:34:41.839  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/usr/local/share/icons/Adwaita/cursors/xterm&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L312" href="#L312">312</a><span class="code-text"><a-p>07:34:41.839  TRACE  window::os::x11::cursor &gt; candidate for Some(Text) is &quot;/usr/share/icons/Adwaita/cursors/xterm&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L313" href="#L313">313</a><span class="code-text"><a-p>07:34:41.839  TRACE  window::os::x11::cursor &gt; Some(Text) resolved to &quot;/usr/share/icons/Adwaita/cursors/xterm&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L314" href="#L314">314</a><span class="code-text"><a-p>07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.local/share/icons/Adwaita/cursors/top_left_arrow&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L315" href="#L315">315</a><span class="code-text"><a-p>07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.local/share/icons/Adwaita/cursors/left_ptr&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L316" href="#L316">316</a><span class="code-text"><a-p>07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.icons/Adwaita/cursors/top_left_arrow&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L317" href="#L317">317</a><span class="code-text"><a-p>07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.icons/Adwaita/cursors/left_ptr&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L318" href="#L318">318</a><span class="code-text"><a-p>07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.local/share/flatpak/exports/share/icons/Adwaita/cursors/top_left_arrow&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L319" href="#L319">319</a><span class="code-text"><a-p>07:34:42.915  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/home/wez/.local/share/flatpak/exports/share/icons/Adwaita/cursors/left_ptr&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L320" href="#L320">320</a><span class="code-text"><a-p>07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/var/lib/flatpak/exports/share/icons/Adwaita/cursors/top_left_arrow&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L321" href="#L321">321</a><span class="code-text"><a-p>07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/var/lib/flatpak/exports/share/icons/Adwaita/cursors/left_ptr&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L322" href="#L322">322</a><span class="code-text"><a-p>07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/usr/local/share/icons/Adwaita/cursors/top_left_arrow&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L323" href="#L323">323</a><span class="code-text"><a-p>07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/usr/local/share/icons/Adwaita/cursors/left_ptr&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L324" href="#L324">324</a><span class="code-text"><a-p>07:34:42.916  TRACE  window::os::x11::cursor &gt; candidate for Some(Arrow) is &quot;/usr/share/icons/Adwaita/cursors/top_left_arrow&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L325" href="#L325">325</a><span class="code-text"><a-p>07:34:42.917  TRACE  window::os::x11::cursor &gt; Some(Arrow) resolved to &quot;/usr/share/icons/Adwaita/cursors/top_left_arrow&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L326" href="#L326">326</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L327" href="#L327">327</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L328" href="#L328">328</a><span class="code-text"><a-p>## </a-p><a-tt>I&#39;m on macOS and wezterm cannot find things in my PATH</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L329" href="#L329">329</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L330" href="#L330">330</a><span class="code-text"><a-p>On macOS, wezterm is typically launched directly by the Finder process and inherits</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L331" href="#L331">331</a><span class="code-text"><a-p>the default and fairly sparse macOS PATH environment.  That&#39;s sufficient for launching</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L332" href="#L332">332</a><span class="code-text"><a-p>your shell, which is then responsible for processing your rcfiles and setting up your</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L333" href="#L333">333</a><span class="code-text"><a-p>PATH.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L334" href="#L334">334</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L335" href="#L335">335</a><span class="code-text"><a-p>However, if you want wezterm to directly spawn some other utility that isn&#39;t in that</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L336" href="#L336">336</a><span class="code-text"><a-p>basic PATH, wezterm will report that it cannot find it.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L337" href="#L337">337</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L338" href="#L338">338</a><span class="code-text"><a-p>Probably the easiest to maintain solution is to change something like:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L339" href="#L339">339</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L340" href="#L340">340</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L341" href="#L341">341</a><span class="code-text"><a-p>wezterm.</a-p><a-v>action</a-v><a-p>.</a-p><a-f>SpawnCommandInNewWindow</a-f><a-p> </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L342" href="#L342">342</a><span class="code-text"><a-p>  </a-p><a-v>args</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-s>&#39;nvim&#39;</a-s><a-p>, </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>config_file</a-v><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L343" href="#L343">343</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L344" href="#L344">344</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L345" href="#L345">345</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L346" href="#L346">346</a><span class="code-text"><a-p>so that it explicitly spawns the command using your shell:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L347" href="#L347">347</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L348" href="#L348">348</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L349" href="#L349">349</a><span class="code-text"><a-p>wezterm.</a-p><a-v>action</a-v><a-p>.</a-p><a-f>SpawnCommandInNewWindow</a-f><a-p> </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L350" href="#L350">350</a><span class="code-text"><a-p>  </a-p><a-v>args</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L351" href="#L351">351</a><span class="code-text"><a-p>    </a-p><a-v>os</a-v><a-p>.</a-p><a-f>getenv</a-f><a-p> </a-p><a-s>&#39;SHELL&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L352" href="#L352">352</a><span class="code-text"><a-p>    </a-p><a-s>&#39;-c&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L353" href="#L353">353</a><span class="code-text"><a-p>    </a-p><a-s>&#39;nvim &#39;</a-s><a-p> </a-p><a-o>..</a-o><a-p> </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>shell_quote_arg</a-f><a-p>(</a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>config_file</a-v><a-p>),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L354" href="#L354">354</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L355" href="#L355">355</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L356" href="#L356">356</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L357" href="#L357">357</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L358" href="#L358">358</a><span class="code-text"><a-p>another option is to explicitly use the full path to the program on your system,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L359" href="#L359">359</a><span class="code-text"><a-p>something like:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L360" href="#L360">360</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L361" href="#L361">361</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L362" href="#L362">362</a><span class="code-text"><a-p>wezterm.</a-p><a-v>action</a-v><a-p>.</a-p><a-f>SpawnCommandInNewWindow</a-f><a-p> </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L363" href="#L363">363</a><span class="code-text"><a-p>  </a-p><a-v>args</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L364" href="#L364">364</a><span class="code-text"><a-p>    </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>home_dir</a-v><a-p> </a-p><a-o>..</a-o><a-p> </a-p><a-s>&#39;/.local/bob/nvim-bin/nvim&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L365" href="#L365">365</a><span class="code-text"><a-p>    </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>config_file</a-v><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L366" href="#L366">366</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L367" href="#L367">367</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L368" href="#L368">368</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L369" href="#L369">369</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L370" href="#L370">370</a><span class="code-text"><a-p>and another other option is to explicitly set the PATH up:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L371" href="#L371">371</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L372" href="#L372">372</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L373" href="#L373">373</a><span class="code-text"><a-p>config.</a-p><a-v>set_environment_variables</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L374" href="#L374">374</a><span class="code-text"><a-p>  </a-p><a-c>-- prepend the path to your utility and include the rest of the PATH</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L375" href="#L375">375</a><span class="code-text"><a-p>  </a-p><a-v>PATH</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>home_dir</a-v><a-p> </a-p><a-o>..</a-o><a-p> </a-p><a-s>&#39;/.local/bob/nvim-bin:&#39;</a-s><a-p> </a-p><a-o>..</a-o><a-p> </a-p><a-v>os</a-v><a-p>.</a-p><a-f>getenv</a-f><a-p> </a-p><a-s>&#39;PATH&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L376" href="#L376">376</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L377" href="#L377">377</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L378" href="#L378">378</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L379" href="#L379">379</a><span class="code-text"><a-p>and yet another option is to configure launchd to use a more expansive</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L380" href="#L380">380</a><span class="code-text"><a-p>PATH for all processes in your user session using `launchctl config user path`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L381" href="#L381">381</a><span class="code-text"><a-p>doing something like this:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L382" href="#L382">382</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L383" href="#L383">383</a><span class="code-text"><a-p>```</a-p><a-tl>console</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L384" href="#L384">384</a><span class="code-text"><a-p>$ sudo launchctl config user path &lt;my path setting&gt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L385" href="#L385">385</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L386" href="#L386">386</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L387" href="#L387">387</a><span class="code-text"><a-p>!!! warning</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L388" href="#L388">388</a><span class="code-text"><a-p>    Take care with setting the user path using this technique, as if you change</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L389" href="#L389">389</a><span class="code-text"><a-p>    that path in a way that system-provided utilities are lower priority than</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L390" href="#L390">390</a><span class="code-text"><a-p>    alternative software that you have installed, you may unexpectedly change</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L391" href="#L391">391</a><span class="code-text"><a-p>    the overall system behavior.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L392" href="#L392">392</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L393" href="#L393">393</a><span class="code-text"><a-p>See also:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L394" href="#L394">394</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L395" href="#L395">395</a><span class="code-text"><a-p> * [set_environment_variables](config/lua/config/set_environment_variables.md)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L396" href="#L396">396</a><span class="code-text"><a-p> * [SpawnCommand](config/lua/SpawnCommand.md)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L397" href="#L397">397</a><span class="code-text"><a-p> * [wezterm.config_file](config/lua/wezterm/config_file.md)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L398" href="#L398">398</a><span class="code-text"><a-p> * [wezterm.shell_quote_arg](config/lua/wezterm/shell_quote_arg.md)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L399" href="#L399">399</a><span class="code-text"><a-p> * [how to set the PATH for Finder-launched applications](https://apple.stackexchange.com/q/51677/166425)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L400" href="#L400">400</a><span class="code-text"><a-p> * </a-p>[what does launchctl config user path do?](https://stackoverflow.com/q/51636338/149111)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L401" href="#L401">401</a><span class="code-text"></span></span></pre></div></div>
</main>
</body>
</html>
