WezTerm Icon WezTerm is a GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust

Download

Features

Looking for a configuration reference?

These docs are searchable: press S or click on the magnifying glass icon to activate the search function!

Screenshot

Screenshot of wezterm on macOS, running vim

WezTerm is available pre-built for the major platforms and, because it is open source, you may also build it for yourself.

Installing on Windows

64-bit Windows 10.0.17763 or later is required to run WezTerm; running on earlier versions of Windows is not possible, as WezTerm requires Pseudo Console support that was first released in Windows 10.0.17763.

You can download a setup.exe style installer to guide the installation (requires admin privileges) or a simple zip file and manage the files for yourself (no special privileges required).

Windows (setup.exe) Nightly Windows (setup.exe)

WezTerm is available in a setup.exe style installer; the installer is produced with Inno Setup and will install wezterm to your program files directory and register that location in your PATH environment. The installer can be run as a GUI to guide you through the install, but also offers the standard Inno Setup command line options to configure/script the installation process.

Windows (zip) Nightly Windows (zip)

WezTerm is also available in a simple zip file that can be extracted and run from anywhere, including a flash drive for a portable/relocatable installation.

  1. Download Release
  2. Extract the zipfile and double-click wezterm.exe to run the UI
  3. Configuration instructions can be found here

For winget users

If you prefer to use the command line to manage installing software, then you may wish to try winget. winget is installed as part of the App Installer that is available from the Microsoft Store.

Once you have winget, you can install wezterm like so:

winget install wez.wezterm

and to later upgrade it:

winget upgrade wez.wezterm

For Scoop users

Another option if you prefer to use the command line to manage installing software, is Scoop.

Wezterm is available from the "Extras" bucket and once you have installed scoop itself can be installed like so:

scoop bucket add extras
scoop install wezterm

For Chocolatey users

If you prefer to use Chocolatey to manage software, wezterm is availabe from the Community Repository. It can be installed like so:

choco install wezterm -y

Installing on macOS

The CI system builds the package on macOS Big Sur and should run on systems as "old" as Mojave. It may run on earlier versions of macOS, but that has not been tested.

Starting with version 20210203-095643-70a364eb, WezTerm is a Universal binary with support for both Apple Silicon and Intel hardware.

Download for macOS Nightly for macOS

  1. Download Release
  2. Extract the zipfile and drag the WezTerm.app bundle to your Applications folder
  3. First time around, you may need to right click and select Open to allow launching the application that your just downloaded from the internet.
  4. Subsequently, a simple double-click will launch the UI
  5. To use wezterm binary from a terminal emulator, like wezterm ls-fonts you'll need to add the location to the wezterm binary folder that exists inside the WezTerm.app, to your environment's $PATH value. For example, to add it to your ~/.zshrc file, and assuming your WezTerm.app was installed to /Applications, add:
PATH="$PATH:/Applications/WezTerm.app/Contents/MacOS"
export PATH
  1. Configuration instructions can be found here

Homebrew

WezTerm is available for brew users in a tap:

$ brew tap wez/wezterm
$ brew install --cask wez/wezterm/wezterm

If you'd like to use a nightly build:

$ brew install --cask wez/wezterm/wezterm-nightly

to upgrade to a newer nightly (normal brew upgrade will not upgrade it!):

$ brew upgrade --cask wezterm-nightly --no-quarantine --greedy-latest

MacPorts

WezTerm is also available via MacPorts:

$ sudo port selfupdate
$ sudo port install wezterm

Installing on Linux via Flathub

WezTerm is available in flatpak format and published on Flathub, which is aggregated into the GNOME Software application and other similar storefront/software catalog applications.

Download on Flathub

To install using the command line:

First, setup flatpak on your system, then:

flatpak install flathub org.wezfurlong.wezterm

and then run:

flatpak run org.wezfurlong.wezterm

You may wish to define an alias for convenience:

alias wezterm='flatpak run org.wezfurlong.wezterm'

Note: flatpaks run in a sandbox so some functionality may behave a little differently when compared to installing the native package format for your system. In particular, starting wezterm using wezterm cli subcommands will block on the first run since you logged in if you haven't already launched the gui.

Only stable releases are allowed to be published to Flathub, so if you want/need to try a nightly download you will need to use one of the other options below.

Installing on Linux using AppImage

WezTerm is available in AppImage format; a self-contained single file that doesn't require installation or any special privileges to run, and that is compatible with a wide range of Linux distributions.

Download and make the file executable and you're ready to run!

AppImage Nightly AppImage

curl -LO https://github.com/wez/wezterm/releases/download/20221119-145034-49b9839f/WezTerm-20221119-145034-49b9839f-Ubuntu18.04.AppImage
chmod +x WezTerm-20221119-145034-49b9839f-Ubuntu18.04.AppImage

You may then execute the appimage directly to launch wezterm, with no specific installation steps required:

./WezTerm-20221119-145034-49b9839f-Ubuntu18.04.AppImage

That said, you may wish to make it a bit more convenient:

mkdir ~/bin
mv ./WezTerm-20221119-145034-49b9839f-Ubuntu18.04.AppImage ~/bin/wezterm
~/bin/wezterm

Installing on Ubuntu and Debian-based Systems

The CI system builds .deb files for a variety of Ubuntu and Debian distributions. These are often compatible with other Debian style systems; if you don't find one that exactly matches your system you can try installing one from an older version of your distribution, or use one of the Debian packages linked below. Failing that, you can try the AppImage download which should work on most Linux systems.

DistroStableNightly
Ubuntu18wezterm-20221119-145034-49b9839f.Ubuntu18.04.debwezterm-nightly.Ubuntu18.04.deb
Ubuntu20wezterm-20221119-145034-49b9839f.Ubuntu20.04.debwezterm-nightly.Ubuntu20.04.deb
Ubuntu22wezterm-20221119-145034-49b9839f.Ubuntu22.04.debwezterm-nightly.Ubuntu22.04.deb
Debian10wezterm-20221119-145034-49b9839f.Debian10.debwezterm-nightly.Debian10.deb
Debian11wezterm-20221119-145034-49b9839f.Debian11.debwezterm-nightly.Debian11.deb

To download and install from the CLI, you can use something like this, which shows how to install the Ubuntu 20 package:

curl -LO https://github.com/wez/wezterm/releases/download/20221119-145034-49b9839f/wezterm-20221119-145034-49b9839f.Ubuntu20.04.deb
sudo apt install -y ./wezterm-20221119-145034-49b9839f.Ubuntu20.04.deb
  • The package installs /usr/bin/wezterm and /usr/share/applications/org.wezfurlong.wezterm.desktop
  • Configuration instructions can be found here

Installing on Fedora and rpm-based Systems

The CI system builds .rpm files on CentOS, Fedora and openSUSE systems. These are likely compatible with other rpm-based distributions. Alternatively, you can try the AppImage download with should work on most Linux systems.

DistroStableNightly
CentOS7wezterm-20221119_145034_49b9839f-1.centos7.x86_64.rpmwezterm-nightly-centos7.rpm
CentOS8wezterm-20221119_145034_49b9839f-1.centos8.x86_64.rpmwezterm-nightly-centos8.rpm
CentOS9wezterm-20221119_145034_49b9839f-1.centos9.x86_64.rpmwezterm-nightly-centos9.rpm
Fedora33wezterm-20221119_145034_49b9839f-1.fedora33.x86_64.rpmwezterm-nightly-fedora33.rpm
Fedora34wezterm-20221119_145034_49b9839f-1.fedora34.x86_64.rpmwezterm-nightly-fedora34.rpm
Fedora35wezterm-20221119_145034_49b9839f-1.fedora35.x86_64.rpmwezterm-nightly-fedora35.rpm
Fedora36wezterm-20221119_145034_49b9839f-1.fedora36.x86_64.rpmwezterm-nightly-fedora36.rpm
openSUSE Leapwezterm-20221119_145034_49b9839f-1.opensuse_leap15.3.x86_64.rpmwezterm-nightly-opensuse_leap.rpm
openSUSE Tumbleweedwezterm-20221119_145034_49b9839f-1.opensuse_tumbleweed20221119.x86_64.rpmwezterm-nightly-opensuse_tumbleweed.rpm

To download and install from the CLI you can use something like this, which shows how to install the Fedora 35 package:

sudo dnf install -y https://github.com/wez/wezterm/releases/download/20221119-145034-49b9839f/wezterm-20221119_145034_49b9839f-1.fedora35.x86_64.rpm

WezTerm is also available in the official Factory repo in openSUSE Tumbleweed. To install from Factory instead from the rpm provided by WezTerm's Github repository, you can use Yast. If you prefer the CLI, you can install it as root user with

zypper addrepo https://download.opensuse.org/repositories/openSUSE:Factory/standard/openSUSE:Factory.repo
zypper refresh
zypper install wezterm
  • The package installs /usr/bin/wezterm and /usr/share/applications/org.wezfurlong.wezterm.desktop
  • Configuration instructions can be found here

Arch Linux

WezTerm is available in the Community repository.

The version available in the community repository may lag behind the latest wezterm release, so you may wish to use one of these AUR options:

WhatWhere
Build from sourcehttps://aur.archlinux.org/packages/wezterm-git/

Alpine Linux

APKs are built out from the main branch.

VersionStableNightly
3.12wezterm-alpine3.12-20221119.145034-r0.apk.sha256wezterm-nightly-alpine3.12.apk.sha256
3.13wezterm-alpine3.13-20221119.145034-r0.apk.sha256wezterm-nightly-alpine3.13.apk.sha256
3.14wezterm-alpine3.14-20221119.145034-r0.apk.sha256wezterm-nightly-alpine3.14.apk.sha256
3.15wezterm-alpine3.15-20221119.145034-r0.apk.sha256wezterm-nightly-alpine3.15.apk.sha256

Linuxbrew Tap

If you are a Linuxbrew user, you can install wezterm from our tap:

$ brew tap wez/wezterm-linuxbrew
$ brew install wezterm

If you'd like to use a nightly build you can perform a head install:

$ brew install --HEAD wezterm

to upgrade to a newer nightly, it is simplest to remove then install:

$ brew rm wezterm
$ brew install --HEAD wezterm

Raw Linux Binary

Another option for linux is a raw binary archive. These are the same binaries that are built for Ubuntu but provided in a tarball.

Download raw Linux binaries Nightly raw Linux binaries

Installing on FreeBSD

WezTerm is available via the ports system.

The most common FreeBSD architectures have pre-built binaries which you can install via:

$ pkg install wezterm

The version available in ports is not directly managed by the release automation of the WezTerm project and may lag behind the latest release. If you need to run a newer version, then the build from source instructions also apply to FreeBSD.

Installing from source

If your system isn't covered by the pre-built packages then you can build it for yourself. WezTerm should run on any modern unix as well as Windows 10 and macOS.

  • Install rustup to get the rust compiler installed on your system. Install rustup
  • Rust version 1.56 or later is required
  • Build in release mode: cargo build --release
  • Run it via either cargo run --release --bin wezterm or target/release/wezterm

You will need a collection of support libraries; the get-deps script will attempt to install them for you. If it doesn't know about your system, please contribute instructions!

If you don't plan to submit a pull request to the wezterm repo, you can download a smaller source tarball using these steps:

curl https://sh.rustup.rs -sSf | sh -s
curl -LO https://github.com/wez/wezterm/releases/download/20221119-145034-49b9839f/wezterm-20221119-145034-49b9839f-src.tar.gz
tar -xzf wezterm-20221119-145034-49b9839f-src.tar.gz
cd wezterm-20221119-145034-49b9839f
./get-deps
cargo build --release
cargo run --release --bin wezterm -- start

Alternatively, use the full git repo:

curl https://sh.rustup.rs -sSf | sh -s
git clone --depth=1 --branch=main --recursive https://github.com/wez/wezterm.git
cd wezterm
git submodule update --init --recursive
./get-deps
cargo build --release
cargo run --release --bin wezterm -- start

If you get an error about zlib then you most likely didn't initialize the submodules; take a closer look at the instructions!

Building without Wayland support on Unix systems

By default, support for both X11 and Wayland is included on Unix systems. If your distribution has X11 but not Wayland, then you can build WezTerm without Wayland support by changing the build invocation:

cargo build --release --no-default-features vendored-fonts

Building without X11 is not supported.

Available Features

Changes

Releases are named using the date, time and git commit hash.

Continuous/Nightly

A bleeding edge build is produced continually (as commits are made, and at least a daily scheduled build) from the main branch. It may not be usable and the feature set may change, but since @wez uses this as a daily driver, its usually the best available version.

As features stabilize some brief notes about them will accumulate here.

New

  • Copy Mode now supports using CTRL-u and CTRL-d to move by half a page at a time. Thanks to @pengux! #2662

20221119-145034-49b9839f

Improved

  • Reduced CPU and RAM utilization, reduced overhead of parsing output and rendering to the GPU.

New

Fixed

  • Wayland: key repeat gets stuck after pressing two keys in quick succession. Thanks to @valpackett! #2492 #2452
  • If the underline attribute was active and CRLF scrolled a new line into the bottom of the display, we'd fill that new line with underlines. #2489
  • Correctly invalidate the display when using wezterm.action.ClearScrollback("ScrollbackAndViewport") #2498
  • Hyperlinks didn't underline on hover #2496
  • base16 color schemes cursor fg/bg were the same. We now also set the indexed colors. Thanks to @valpackett! #2491
  • Panic when processing a sixel with inconsistent width information #2500
  • Cells with the invisible/hidden attribute are now invisible
  • Panic when trying to activate the search overlay when the launcher menu is active #2529
  • Overlays did not see config overrides set via window:set_config_overrides #2544
  • Closing a window while tab had a zoomed pane would leave the other panes untouched and wezterm would linger in the background #2548
  • CharSelect panic when pressing enter when no matches were found #2580
  • Panic when setting initial_rows or initial_cols to 0 #2593
  • X11: Crash on systems using DRI2 based Intel graphics #2559
  • Missing validation of conflicting domain names #2618
  • Creating tabs in a multiplexing domain could fail after previously closing all tabs connected to that domain in that window #2614
  • CharSelect now uppercases hex digit input for better compatibility with QMK-based keyboards that send eg: CTRL-SHIFT-U e 1 <ENTER>. #2581
  • Multiple active multiplexer client domain connections could result in showing duplicate tabs in a window #2616
  • Incorrect line width when applying hyperlink rules to a wrapped line containing double-wide cells. #2568
  • Incorrect shaping for U+28 U+FF9F #2572
  • Panic when hitting enter in launcher menu when no fuzzy results match #2629
  • Default CTRL-SHIFT-<NUM> assignments didn't work on Windows and X11 systems when key_map_preference = "Mapped" #2623
  • Panic when calling window:set_workspace when the default domain is a multiplexer domain. #2638
  • nvim's title and titlestring options don't work when TERM=wezterm. #2112
  • Horizontal wheel scrolling generated incorrect mouse events #2649
  • Cursor color changes did not always render #2708
  • Unable to set cursor on Wayland/X11 #2687 #2743
  • Default MoveTabRelative assignments were incorrectly set to SUPER+SHIFT+Page(Up|Down) instead of the documented CTRL+SHIFT+Page(Up|Down) #2705
  • Dragging by retro tab bar left or right status area would jump around erratically. #2758
  • Fixed background Cover algorithm. Thanks to @xiaopengli89! #2636
  • wezterm start --cwd . didn't use the cwd of the spawned process when the wezterm gui was already running. Thanks to @exactly-one-kas! #2661
  • IME composition text and cursor color incorrectly applied to all panes rather than just the active pane. #2569

Changed

  • Removed Last Resort fallback font
  • X11: use _NET_WM_MOVERESIZE to drag by tab bar, when supported by the WM #2530
  • tab:panes() and tab:panes_with_info() now return the full list of panes in the tab regardless of whether a pane was zoomed. Previously, if a pane was zoomed, only that pane would be returned by those methods.
  • macOS: CTRL-modified keys are now routed to the IME #2435
  • multiplexer: The lag indicator that gets overlaid on the pane content when waiting a long time for a response now defaults to disabled. It is recommended that you put it into your status bar, but you may re-enable the old way using overlay_lag_indicator = true in the appropriate domain configuration.
  • Added dummy -e command line option to support programs that assume that all terminal emulators support a -e option. Thanks to @vimpostor!. #2670 #2622 #2271
  • Windows: installer no longer prevents installing the x64 binary on arm64 systems. The x64 executable is installed and run via emulation. Thanks to @xeysz! #2746 #2667

Updated

  • Bundled Nerd Font Symbols font to v2.2.2
  • Bundled harfbuzz to 5.3.1

20220905-102802-7d4b8249

New

Changed

  • fontconfig: when locating a fallback font for a given codepoint, allow matching non-monospace fonts if we can't find any matching monospace fonts. #2468
  • os.getenv now knows how to resolve environment variables that would normally require logging out to update, such as SHELL (if you chsh on unix systeams), or those set through the registry on Windows. #2481
  • Searching is now incremental and shows progress. #1209

Fixed

  • Hangul in NFD incorrectly shaped #2482
  • Visual artifacts when resizing splits #2483

20220904-064125-9a6cee2b

  • Fix build on architectures where c_char is u8 instead of i8. Thanks to @liushuyu! #2480

20220903-194523-3bb1ed61

New

Changed

  • colors now override colors from your selected color_scheme. Previously, color_scheme was mutually exclusive with colors and always took precedence. The new behavior is more in line with what most people expect.
  • Reduced CPU utilization for busy/large screen updates, blinking cursor and other easing animations
  • ActivatePaneDirection now uses recency to resolve ambiguous moves #2374
  • update-status is a more general event for updating left or right status. update-right-status is considered to be deprecated in favor of update-status.
  • Cache XDG Portal Appearance values. Thanks to @vimposter! #2402
  • Compensate for TUI programs that flicker due to unsynchronized output by adding up to 3ms additional latency after each read to coalesce their screen outputs into a single frame. You can set this delay via a new mux_output_parser_coalesce_delay_ms option. #2443
  • win32: Updated openconsole/conpty to v1.14.2281.0

Fixed

  • macOS: crash on startup if $SHELL points to something that isn't executable. #2378
  • tab titles truncated too short #2379
  • bypass_mouse_reporting_modifiers stopped working (regression around new mouse binding logic) #2389
  • Entering IME-composed text would have no effect in wezterm ssh #2434
  • gui-startup event now also works with wezterm ssh
  • x and + buttons in the fancy tab bar are now always square #2399
  • middle clicking a tab to close it will now confirm closing using the same rules as CloseCurrentTab #2350
  • Emitting the tmux-style ESC k TITLE ST sequence via ConPTY breaks output for the pane #2442
  • Avoid using full path canonicalization for --cwd options #2449
  • Scroll to the bottom on mouse input when mouse reporting is enabled #2447
  • ssh: correctly expand %h ssh_config tokens #2448
  • ssh: CloseCurrentPane wouldn't release all resources associated with the pane and could lead to a too many open files error for a long running wezterm ssh session. #2466
  • mouse cursor is now reset to arrow when the mouse leaves the window #2471

20220807-113146-c2fee766

New

Changed

  • If timeout_milliseconds is specified in ActivateKeyTable, then the timeout duration is now reset each time a key press matches that key table activation. #1129
  • The lua examples in the docs are now syntax checked and formatted via Gelatyx and StyLua, thanks to @azzamsa! #2273 #2253
  • Internal scrollback datastructure improvements reduce per-cell overhead by up to ~40x depending on the composition of the line (lines with lots of varied attributes or image attachments will have more overhead).
  • Improved search performance
  • Quickselect: now defaults to searching 1000 lines above and below the current viewport, making it faster and the labels shorter for users with a larger scrollback. A new scope_lines parameter to QuickSelectArgs allows controlling the search region explicitly. Thanks to @yyogo for the initial PR! #1317
  • OSC 10, 11 and 12 (Set Default Text Background, Default Text Foreground Color, and Text Cursor Color) now support setting the alpha component #2313, and added CSI 38:6, CSI 48:6 and CSI 58:6 extensions to allow setting full color RGB with Alpha channel for spans of text.
  • Copy Mode: setting the same selection mode a second time will now toggle off that mode and clear the selection, preserving the current position #2246
  • Copy Mode: new default vim-style y "yank" key assignment will copy the selection and close copy mode

Fixed

  • ActivateKeyTable's replace_current field was not actually optional. Made it optional. #2179
  • winget causes toast notification spam #2185
  • wezterm connect sshdomain could hang on startup if password authentication was required #2194
  • colors.indexed would error out with Cannot convert String to u8. #2197
  • X11: closing a window when multiple were open could result in an X protocol error that closed all windows #2198
  • Config will now automatically reload after error. Previously, you would need to manually reload the config using ReloadConfiguration. #1174
  • Config will now automatically reload for changes made to required lua files. Previously, only the main config file and any files that you explicitly passed to add_to_config_reload_watch_list would trigger a reload.
  • macOS: numeric keypad enter generated CTRL-C instead of enter. Regression of #739. #2204
  • Wayland: inconsistent pasting. Thanks to @Funami580! #2225 #2226
  • win32 input mode: fixed encoding of backspace and delete keys. Thanks to @kreudom! #2233
  • Tab bar could glitch and show incorrect contents when adjusting for monitor or changed font scaling #2208
  • Wayland: transparent gap under tab bar when window is transparent, split and using per-pane color schemes #1620
  • Tab bar could show a gap to the right when resizing
  • Padding could show window background rather than pane background around split panes at certain window sizes #2210
  • Loading dynamic escape sequence scripts from the iTerm2-Color-Scheme dynamic-colors directory would only apply the first 7 colors
  • Unix: Clicking a URL when no browser is open could cause wezterm to hang until the newly opened browser is closed. #2245
  • Quickselect: now selects the bottom-most match rather than the top-most match. #2250
  • Mux: wezterm.mux.set_active_workspace didn't update the current window to match the newly activated workspace. #2248
  • Overlays such as debug and launcher menu now handle resize better
  • Shift-F1 through F4 generated different encoding than xterm #2263
  • X11/Wayland: apps that extract the Exec field from wezterm.desktop (such as thunar, Dolphin and others) can now simply concatenate the command line they want to invoke, and it will spawn in the their current working directory. Thanks to @Anomalocaridid! #2271 #2103
  • gui-startup now passes a SpawnCommand parameter representing the wezterm start command arguments.
  • Tab x button is no longer obscured by tab title text for long tab titles #2269
  • Cursor position could end up in the wrong place when rewrapping lines and the cursor was on the rewrap boundary #2162
  • Two or more panes closing at the same time could result in their containing tab hanging and being stuck with "no pane" for a title #2304
  • Visual Bell now fills out to the adjacent window edges rather than being constrained by the padding. #2364

Updated

  • Bundled harfbuzz to 5.1.0

20220624-141144-bd1b7c5d

New

Updated

  • Bundled harfbuzz to 4.3.0

Changed

  • Debian packages now register wezterm as an alternative for x-terminal-emulator. Thanks to @xpufx! #1883
  • Windows: wezterm will now read the default environment variables from the HKLM\System\CurrentControlSet\Control\Session Manager\Environment and HKCU\Environment and apply those to the base environment prior to applying set_environment_variables. #1848
  • Key Table lookups will now keep searching the activation stack until a matching assignment is found, allowing for layered key tables. #993
  • Search mode's search term is now remembered per-tab between activations of search mode. #1912
  • Quickselect no longer jumps to the bottom of the viewport when activated, allowing you to quickselect within the current viewport region
  • Quickselect now supports multi-line anchors such as ^ and $. #2008
  • Overriding config using the cli --config option will now error out and prevent starting up if unknown config options are specified, or if the value evaluates to nil. Unknown options continue to generate warnings (rather than errors) when observed in the config file so that you're not "locked out" of wezterm if you make a typo in the config file.
  • Windows: allow_win32_input_mode now defaults to true and enables using win32-input-mode to send high-fidelity keyboard input to ConPTY. This means that win32 console applications, such as FAR Manager that use the low level INPUT_RECORD API will now receive key-up events as well as events for modifier-only key presses. #1509 #2009 #2098 #1904
  • Wayland: enable_wayland now defaults to true. #2104
  • exit_behavior now defaults to "Close". #2105
  • Improved wezterm.action syntax for slightly more ergnomic and understandable key assignments. #1150

Fixed

  • Flush after replying to XTGETTCAP, DECRQM, XTVERSION, DA2, DA3 #2060 #1850 #1950
  • macOS: CMD-. was treated as CTRL-ESC #1867
  • macOS: CTRL-Backslash on German layouts was incorrect #1891
  • nf-mdi-contacts nerdfont symbol treated as zero-width #1864
  • X11/Wayland: CTRL-i, CTRL-j, CTRL-m misinterpreted as CTRL-Tab, CTRL-Enter, CTRL-Return #1851
  • Scrollbar stopped working after a lot of output scrolled outside of the scrollback limit. Thanks to @davidrios! #1866
  • Windows: uncommitted IME composition could get stuck when switching input methods. #1922
  • OSC sequences, such as those that change the window or tab title, that accept a single string parameter will now join multiple parameters together. This allows window and tab titles to contain a semicolon. Thanks to @kumattau! #1939
  • Unable to use ALT as a modifier for the leader key. #1958
  • IME Candidate window position was incorrect. Thanks to @kumattau and @aznhe21! #1976 #2001 #2022
  • Prevent panic for some classes of invalid input, found while fuzzing. Thanks to @5225225! #1990 #1986
  • Detaching an ssh multiplexer domain sometimes killed the associated panes! #1993
  • DecreaseFontSize wasn't quite the inverse of IncreaseFontSize. Thanks to @Funami580! #1997
  • Wayland: unable to paste text that was copied before starting the initial wezterm window. Thanks to @Funami580! #1994 #1385
  • Unicode NFD text could incorrectly render with repeated glyphs #2032
  • Windows: spawning new panes/tabs wouldn't automatically use the working directory of the current pane when OSC 7 was not being used #2036
  • Wayland: panic when display scaling is enabled. #1727
  • Dark+ color scheme background color #2013
  • Synthesized bold didn't kick in for automatically computed font_rules. #2074
  • Added freetype_pcf_long_family_names option to workaround PCF font naming issues on certain Linux distributions. #2100
  • X11/Wayland: wezterm.desktop now specifies StartupWMClass. Thanks to @uncomfyhalomacro! #2052 #2125
  • sudo -i in a pane would cause subsequent pane/tab creation to fail until the cwd was changed to an accessible directory #2120
  • X11: Fixed an issue where some events could get lost around resize events, especially prevalent when using the NVIDIA proprietary drivers. Thanks to @pjones123 and @yuttie for working through this! #1992 #2063 #2111 #1628
  • macOS: SHIFT-Tab and CTRL-SHIFT-Tab produced incorrect results #1902
  • X11: Fixed an issue where copy and paste between two wezterm windows could produce stale results. #2110
  • Mouse selection spanning multiple lines always included the first column even when the mouse was to the left of the first column. Thanks to @Funami580! #2106
  • Fonts: Codepoints for eg: symbol glyphs that were not explicitly listed in your font fallback list may not be resolved when used in styled (eg: bold) text. #1913 #2158

20220408-101518-b908e2dd

New

  • Key Tables feature for powerful modal key assignments
  • wezterm start --position x,y, wezterm start --position displayname:30%,30% option to control starting window position on all systems except for Wayland. See wezterm start --help for more info. #1794

Changed

  • Default key assignments are mapped: again. A new key_map_preference option allows the defaults to use "Mapped" or "Physical".
  • Disabled ligatures for "Monaco" and "Menlo" fonts, as those have "fi" ligatures that match even for words such as find. #1786 #1736
  • Removed the send_composed_key_when_alt_is_pressed option. When processing generic ALT (eg: that has neither left nor right), if either send_composed_key_when_left_alt_is_pressed or send_composed_key_when_right_alt_is_pressed is true, then the composed form of the key event will be generated.

Updated and Improved

  • Bundled harfbuzz to 4.2.0
  • On macOS, non-native fullscreen mode now attempts to avoid the notch on systems that have one. #1737
  • Sixel parsing performance has been improved
  • You may now specify a scaling factor per fallback font, which is useful when your preferred CJK font renders smaller than your Roman primary font, for example.
  • Color schemes: Retro, GitHub Dark, Blazer
  • Wayland: touchpad scroll is now more responsive/precise. Thanks to @davidrios! #1800 #1840
  • Kitty image protocol: now also supports shared memory data transmission. Thanks to @tantei3! #1810
  • Secondary DA response bumped up to persuade vim to set ttymouse=sgr by default. #1825

Fixed

  • Incorrect csi-u encoding with non-ascii characters. #1746
  • X11 _NET_WM_ICON had red/blue channels swapped #1754
  • ls-fonts output didn't quote the style field #1762
  • window_decorations = "RESIZE" on Windows prevented minimize/maximize and aerosnap, double click to maximize, and had an ugly top border. Many thanks to @davidrios! #1674 #1675 #1771
  • On Windows, explorer shortcut icons with the maximized setting would fall out of maximized state on startup. Thanks to @davidrios! #1502
  • LANG environment variable was not always set on macOS, leading to mojibake when entering CJK. #1761 #1765
  • Fonts with only non-unicode names (eg: only using a Chinese multibyte string encoding) were treated as having names like ????? and were not accessible. #1761
  • Hover state of leftmost retro style tab was overly sticky when the mouse moved out of the tab. #1764
  • On macOS, the font size could incorrectly double or halve after waking from sleep or moving the window to/from an external monitor. #1566 #1745
  • On Windows, touchpad scrolling was janky. Many thanks to @davidrios! #1773 #1725 #949
  • X11: workaround i3-gaps not sending initial CONFIGURE_NOTIFY or FOCUS events, leading to weird initial window size and broken focus status. #1710 #1757
  • Hyperlink rules with more captures than replacements could panic wezterm when text matched. #1780
  • Malformed XTGETTCAP response. #1781
  • Multiplexer performance with images was unusuable for all but tiny images. #1237
  • CloseCurrentPane{confirm=false} would leave behind a phantom tab/pane when used with the multiplexer. #1277
  • CloseCurrentPane{confirm=true} artifacts when used with the multiplexer. #783
  • Scrollbar thumb could jump around/move out of bounds. Thanks to @davidrios! #1525
  • OSC 52 could stop working for tabs/panes spawned into the GUI via the CLI. #1790
  • Workaround for fonts with broken horizontal advance metrics #1787
  • Improved mouse based selection. Thanks to @davidrios! #1805 #1199 #1386 #354
  • X11 KP_End wasn't recognized #1804
  • fontconfig matches now also treat "charcell" spacing as monospace. #1820
  • Multiplexer render update laggy, especially when using multiple windows. #1814 #1841

20220319-142410-0fcdea07

New

Changed

  • Key Assignments now use Physical Key locations by default!! Read more #1483 #601 #1080 #1391
  • Key assignments now match prior to any dead-key or IME composition #877
  • Removed the ALT-[NUMBER] default key assignments as they are not good for non-US layouts. #1542
  • wezterm cli, when run outside of a wezterm pane, now prefers to connect to the main GUI instance rather than background mux server. Use wezterm cli --prefer-mux to ignore the GUI instance and talk only to the mux server. See wezterm cli --help for additional information.
  • ScrollByPage now accepts fractional numbers like 0.5 to scroll by half a page at time. Thanks to @hahuang65! #1534
  • use_ime now defaults to true on all platforms; previously it was not enabled by default on macOS.
  • canonicalize_pasted_newlines default has changed to be more compatible for nano users, and now provides more control over the text format that is pasted. #1575
  • Blinking text is now eased rather than binary-blinked. See text_blink_ease_in and text_blink_ease_out, text_blink_rapid_ease_in and text_blink_rapid_ease_out for more information.
  • Blinking text cursor is now eased rather than binary-blinked. See cursor_blink_ease_in and cursor_blink_ease_out.

Updated and Improved

  • IME and dead key composition state now shows inline in the terminal using the terminal font (All platforms, except Wayland where we only support dead key composition)
  • macOS: use_ime=true no longer prevents key repeat from working with some keys #1131
  • Bundled harfbuzz to 4.0.1

Fixed

  • Regression that broke fontconfig aliases such as "monospace" #1250
  • Windows/X11/Wayland: CTRL+C in non-latin keyboard layouts wouldn't send CTRL+C #678
  • The new tab button in the fancy tab didn't respect new_tab_hover colors #1498
  • Font baseline alignment when mixing symbols/emoji with the main text #1499
  • Glitchy window resize #1491
  • Ligatured glyphs no longer turn partially black when cursoring through them #478
  • Kitty Image Protocol: didn't respect c and r parameters to scale images
  • Cursor location on the primary screen wasn't updated correctly if the window was resized while the alternate screen was active #1512
  • Windows: latency issue with AltSnap and other window-managery things #1013 #1398 #1075 #1099
  • Multiplexer sessions now propagate user vars #1528
  • Config reloads on the multiplexer server didn't cause the palette to update on the client #1526
  • ScrollToPrompt could get confused when there were multiple prompts on the same line #1121
  • Hangul text in NFD was not always correctly composed when shaping fonts. #1573
  • Avoid OOM when processing sixels with huge repeat counts #1610
  • Set the sticky bit on socket and pid files created in XDG_RUNTIME_DIR to avoid removal by tmpwatch #1601
  • Shaping combining sequences like e U+20d7 could "lose" the vector symbol if the font produced an entry with no x_advance. #1617
  • Setting the cursor color via escape sequences now take precedence over force_reverse_video_cursor. #1625
  • Fixed Detection of DECSDM support via DECRQM/DECRPM, Correct sixel image placement when DECSDM is set and VT340 default sixel colors. Thanks to Autumn! #1577
  • Fixed missing whitespace from intermediate lines when copying a wrapped logical line #1635
  • Unable to match Iosevka Term when multiple iosevka ttc files were installed on macOS #1630
  • Incorrect umask for panes spawned via the multiplexer server #1633
  • Fall back from top_left_arrow to left_ptr when loading XCursor themes #1655
  • Fixed lingering hover state in titlebar when the mouse pointer left the window. Thanks to @davidrios! #1434
  • We now respect the difference between Italic and Oblique font styles when matching fonts. You may explicitly specify style="Oblique" rather than using italic=true for fonts that offer both italic and oblique variants. #1646
  • Hang when clicking a URL would launch the browser for the first time on unix systems #1721
  • Wayland input handling gets broken after suspend/resume. Thanks to @LawnGnome! #1497

20220101-133340-7edc5b5a

New

Changed

  • quickselect: we now de-duplicate labels for results with the same textual content. #1271
  • The default CompleteSelectionOrOpenLinkAtMouseCursor left button release assignment now also accepts SHIFT being held in order to make SHIFT-click ExtendSelectionToMouseCursor feel more ergonomic if the mouse button is released before the SHIFT key. #1204
  • Unicode BIDI and other zero-width graphemes are now filtered out from the terminal model. It's not ideal in the sense that that information is essentially lost when copying to the clipboard, but it makes the presentation correct. #1422
  • use_ime now defaults to true on X11 systems

Updated and Improved

  • Bundled harfbuzz to 3.2.0
  • Bundled freetype to 2.11.1
  • Bundled NotoColorEmoji to 2.034 (with Unicode 14 support) Thanks to @4cm4k1! #1440
  • macos: removing the titlebar from window_decorations now preserves rounded window corners #1034
  • Colors can now be specified in the HSL colorspace using syntax like "hsl:235 100 50" #1436
  • Line/Bar cursors in force_reverse_video_cursor mode now use the text foreground color rather than the cursor border color. #1076
  • Improved logo appearance. Thanks to @ghifarit53! #1454
  • You can now pass SendKey to wezterm.action and make your keys config look more consistent
  • Mouse wheel events are now routed to the hovered pane, rather than sent to the focused pane #798

Fixed

  • DECSTR (terminal soft reset) now turns off DECLRMM (left and right margin mode). Thanks to @ninjalj! #1376
  • Improved conformance of CUP, HVP, SLRM, STBM escape sequences by support empty first parameter. Thanks to @ninjalj! #1377
  • tab bar didn't correctly handle double-wide cells and could truncate at edges when using format-tab-title #1371
  • wezterm cli --no-auto-start was not respected
  • Pixel geometry configured on the PTY in new windows could be incorrect on HiDPI displays until the window was resized #1387
  • Image attachment geometry for imgcat and sixels could stretch the image across the rounded up number of cells that contained the image. #1300, #1270
  • Closing a split pane created inside a wezterm ssh session wouldn't actually close the pane #1197
  • Clicking when unfocused could lead to unwanted text selection #1140 #1310
  • Changing font scaling on Windows no longer causes the initial terminal rows/cols to be under-sized #1381
  • New version update notifications are now more coordinated between multiple wezterm GUI instances, and update related configuration now respects configuration reloading. #1402
  • TLS domains bootstrapping via SSH now use the libssh backend by default and work more reliably on Windows
  • Closing a window will no longer recursively terminate contained multiplexer client panes; the window will instead be restored when you next connect to that multiplexer server. Killing/closing individual tabs/panes will kill the panes; this change only affects closing the window. #848 #917 #1224
  • Colors were too intense due to over gamma correction #1025
  • Mesa and EGL colors were too dim due to under gamma correction #1373
  • wezterm ssh no longer tries to use default_prog or default_cwd when spawning additional panes on the remote host #1456
  • Launcher menu WSL items now launch correctly on non-US versions of Windows #1462
  • Korean text in NFD form is now correctly sized and rendered #1474
  • macOS: use_ime=true conflicted with LEADER key assignments #1409
  • macOS: certain keys (eg: F8 and F9) did nothing when use_ime=true. #975
  • Splitting a tab would cause the window to lose its transparency #1459

20211205-192649-672c1cc1

Fixed

  • Windows: wezterm <something> would fail silently when spawning wezterm-gui under the covers. Regression introduced by #1278. Workaround is to directly spawn wezterm-gui.
  • Windows: the PTY handles were ignored in favor of the redirected stdio handles of the parent of the wezterm mux process #1358
  • Windows: Failure to spawn wezterm when launching an ssh mux domain session no longer waits forever
  • "Update available" message kept showing even though already running the latest version #1365

20211204-082213-a66c61ee9

New

  • X11 now supports IME. It currently defaults to disabled, but you can set use_ime = true in your config to enable it (you need to restart wezterm for this to take effect). Many thanks to @H-M-H for bringing xcb-imdkit to Rust and implementing this in wezterm! #250 #1043
  • it is now possible to define colors in the range 16-255 in colors and color scheme definitions. Thanks to @potamides! #841 #1056
  • Added SendKey key assignment action that makes it more convenient to rebind the key input that is sent to a pane.
  • Added Multiple key assignment action for combining multuple actions in a single press.
  • Added use_resize_increments option to tell X11, Wayland, macOS window resizing to prefers to step in increments of the cell size
  • visual_bell and audible_bell configuration options, as well as a bell event allows you to trigger lua code when the bell is rung. #3
  • wezterm.action_callback function to make it easier to use custom events. Thanks to @bew! #1151
  • wezterm connect now also supports the --class parameter to override the window class
  • window_padding now accepts values such as "1cell" or "30%" to compute values based on font or window metrics.
  • BSDish systems now support toast notifications
  • wezterm.background_child_process function to spawn a process without waiting.
  • mux_env_remove setting to control which environment variables should be cleared prior to spawning processes in the multiplexer server #1225
  • canonicalize_pasted_newlines option to help Windows users manage newlines in pastes #1213
  • SSH client now uses libssh by default. ssh_backend can be used to change this.
  • unzoom_on_switch_pane option. Thanks to @yyogo #1301
  • unicode_version option and corresponding OSC escape sequences that affects how the width of certain unicode sequences are interpreted.
  • macOS: binaries produced by wezterm's CI are now codesigned, which resolves some spurious permission dialogs that affected some users #482

Changed

  • new default key assignments: CTRL+PageUp and CTRL+Tab activate next tab, CTRL+PageDown and CTRL+SHIFT+Tab activate previous tab. ALT+{1..8} directly select the first through 8th tabs. Thanks to @friederbluemle! #1132
  • X11: we now allow matching visuals with >= 8 bits per rgb value. Previously, we only matched exactly 8 bits. This improve compatibility with systems that have the COMPOSITE extension disabled. Thanks to @shizeeg! #1083
  • The incomplete Allsorts shaper was removed.
  • Windows: wezterm-gui.exe now only grabs the parent process' console handle when spawned from wezterm.exe, which prevents some frustrating interactions when launching wezterm-gui.exe via start in cmd/powershell. #1278
  • AppImage: take care to remove APPIMAGE related environment when spawning child processes. Thanks to @srevinsaju! #1338

Updated and Improved

  • bundled harfbuzz updated to version 3.0.0, bundled freetype updated to 2.11
  • window close confirmations now accept both uppercase and lowercase Y/N key presses. Thanks to @SpyrosRoum! #1119
  • multi-click-streaks are now interrupted by the cursor moving to a different cell. Thanks to @valpackett! #1126
  • .deb packages now Provides: x-terminal-emulator. #1139
  • use_cap_height_to_scale_fallback_fonts now computes cap-height based on the rasterized glyph bitmap which means that the data is accurate in more cases, including for bitmap fonts. Scaling is now also applied across varying text styles; previously it only applied to a font within an wezterm.font_with_fallback font list.
  • Can now match fontconfig aliases, such as monospace, on systems that use fontconfig. Thanks to @valpackett! #1149
  • Powerline semicircle glyphs now look much better. Thanks to @bew and @sdrik! #1311
  • Splits now look better, especially when using escape sequences to change the default background color #1256

Fixed

  • wezterm cli spawn would use the initial terminal size for a new tab, rather than using the current tab size #920
  • text_background_opacity opacity was not respected
  • spawning commands via the mux didn't respect the PATH configured in set_environment_variables. #1029
  • cursor could have a transparent "hole" through the window with certain cursor styles
  • Consolas font + random input could cause a divide-by-zero when computing glyph metrics #1042
  • Emoji fallback was too strict in respecting VS15/VS16 presentation selection, adjust the fallback to allow showing Emoji/Text presentation if Text/Emoji was requested but not found.
  • X11: laggy input after selecting text. #1027
  • macOS: send_composed_key_when_left_alt_is_pressed and send_composed_key_when_right_alt_is_pressed are now respected when use_ime=true. Thanks to @jakelinnzy! #1096
  • X11: jittery resize with some window managers #1051
  • X11: window:get_appearance now actually returns Dark when the theme is dark. #1098
  • ALT + Arrow, PageUp/PageDown, Ins, Del, Home, End incorrectly sent ESC prefixed key sequences. #892
  • Crash due to Out of Memory condition when the iTerm2 protocol was used to send excessively large PNG files #1031
  • DCH (delete char) sequence would remove cells and replace them with default-blank cells instead of blank-cells-with-current-bg-color. #789
  • invisible I-beam or underline cursor when force_reverse_video_cursor = true #1076
  • SU (scroll up) sequence would fill with default-blank cells instead of blank-cells-with-current-bg-color. #1102
  • X11: computed but did not use the correct DPI for HiDPI screens #947
  • performance when resolving fallback fonts via fontconfig, and of coverage calculation with freetype. Thanks to @H-M-H!
  • Wayland: incorrect initial surface size for HiDPI screens. Thanks to @valpackett! #1111 #1112
  • invisible cursor in CopyMode when using kakoune #1113
  • Wayland: bypass_mouse_reporting_modifiers didn't work. Thanks to @valpackett! #1122
  • new tabs could have the wrong number of rows and columns if a tiling WM resizes the window before OpenGL has been setup. #1074
  • Wayland: dragging the window using the tab bar now works. Thanks to @valpackett! #1127
  • error matching a font when that font is in a .ttc that contains multiple font families. #1137
  • Wayland: panic with most recent wlroots. Thanks to @valpackett! #1144
  • incorrect spacing for IDEOGRAPHIC SPACE. #1161
  • italic fonts weren't always recognized as being italic, resulting in italic variants being used instead of the non-italic variants in some cases! #1162
  • Ask freetype for cell metrics in bitmap-only fonts, rather than simply taking the bitmap width. #1165
  • wezterm can now match bitmap fonts that are spread across multiple font files #1189
  • ssh config parser incorrectly split Host patterns with commas instead of whitespace #1196
  • search now auto-updates when the pane content changes #1205
  • fonts with emoji presentation are shifted to better align with the primary font baseline #1203
  • the whole tab was closed when only the zoomed pane exited. #1235
  • multiplexer: wrong WEZTERM_UNIX_SOCKET environment passed to children when using unix domain sockets and connect_automatically=true #1222
  • multiplexer: spawning remote tabs didn't correctly record local tab mapping, resulting in phantom additional tabs showing in the client. #1222
  • wezterm ls-fonts --text "✘" didn't account for the system fallback list. #849
  • macOS: The Menlo font is now implicitly included in the system fallback list, as it is the only font that contains U+2718 ✘
  • wezterm cli spawn --cwd .. and wezterm cli split-pane --cwd .. now resolve relative paths #1243
  • Incorrect DECRPTUI response to DA3. Thanks to @ninjalj! #1330
  • Reloading config now loads newly defined multiplexer domains, however, existing domains are not updated. #1279

20210814-124438-54e29167

  • Fixed: ssh client would read /etc/ssh/config rather than the proper /etc/ssh/ssh_config
  • Updated: ssh client now processes Include statements in ssh config
  • x11: support for VoidSymbol in key assignments. Thanks to @digitallyserviced! #759
  • Fixed: UTF8-encoded-C1 control codes were not always recognized as control codes, and could result in a panic when later attempting to update the line. #768
  • Fixed: wezterm cli split-pane didn't use the current working dir of the source pane. #766
  • Fixed: double-click-drag selection could panic when crossing line boundaries #762
  • Fixed: wrong scaling for ligatures in Recursive Mono font #699
  • Fixed: incorrect Sixel HLS hue handling #775
  • Fixed: we now recognize the CSI 48:2:0:214:255m form of specifying true color text attributes #785
  • Fixed: split separators didn't respect tab_bar_at_bottom=true and were rendered in the wrong place #797
  • Improved: messaging around exit_behavior
  • Fixed: errors loading custom color schemes are now logged to the error log #794
  • Fixed: OSC 7 (current working directory) now works with paths that contain spaces and other special characters. Thanks to @Arvedui! #799
  • Changed: the homebrew tap is now a Cask that installs to the /Applications directory on macOS. Thanks to @laggardkernel!
  • New: bold/dim and/or italics are now synthesized for fonts when the matching font is not actually italic or doesn't match the requested weight. #815
  • Updated: conpty.dll to v1.9.1445.0; fixes color bar artifacts when resizing window and allows win32 console applications to use mouse events
  • Fixed: Windows: pane could linger after the process has died, closing only when a new pane/tab event occurs
  • Fixed: Windows: first character after wezterm ssh keyboard authention was swallowed #771
  • Fixed: Windows: detect window resizes while authenticating for wezterm ssh #696
  • Fixed: OSC 52 clipboard escape didn't work in the initial pane spawned in the multiplexer server #764
  • Fixed: splitting panes in multiplexer could fail after a network reconnect #781
  • Fixed: multiplexer now propagates toast notifications and color palette to client #489 #748
  • Fixed: neovim interprets drags as double clicks #823
  • New: CTRL+SHIFT+L is assigned to ShowDebugOverlay #641
  • Improved: antialiasing for undercurl. Thanks to @ModProg! #838
  • Fixed: wezterm start --cwd c:/ didn't run default_prog. Thanks to @exactly-one-kas! #851
  • Improved: skip_close_confirmation_for_processes_named now includes common windows shell processes cmd.exe, pwsh.exe and powershell.exe. #843
  • Fixed: don't keep the window alive after running something & disown ; exit #839
  • Improved: we now draw sextant glyphs from the Unicode Symbols for Legacy Computing block (1FB00) when custom_block_glyphs is enabled.
  • Changed: COLORTERM=truecolor is now set in the environment. #875
  • New: wezterm cli spawn --new-window flag for creating a new window via the CLI #887
  • Fixed: closing last pane in a tab via CloseCurrentPane could cause the window to close #890
  • Improved: wezterm ls-fonts --list-system shows all available fonts, wezterm ls-fonts --text "hello" explains which fonts are used for each glyph in the supplied text
  • Fixed: mouse cursor is now Arrow rather than I-beam when the application in the terminal has enabled mouse reporting #859
  • Improved: DEC Special Graphics mode conformance and complete coverage of the graphics character set. Thanks to Autumn Lamonte! #891
  • Fixed: click to focus now focuses the pane under the mouse cursor #881
  • Removed: Parasio Dark color scheme; it was a duplicate of the correctly named Paraiso Dark scheme. Thanks to @adrian5! #906
  • Fixed: key repeat on Wayland now respects the system specified key repeat rate, and doesn't "stick". #669
  • Fixed: force_reverse_video_cursor wasn't correctly swapping the cursor colors in all cases. #706
  • Fixed: allow multuple IdentityFile lines in an ssh_config block to be considered
  • Improved: implement braille characters as custom glyphs, to have perfect rendering when custom_block_glyphs is enabled. Thanks to @bew!
  • Fixed: Mod3 is no longer treater as SUPER on X11 and Wayland #933
  • Fixed: paste now respects scroll_to_bottom_on_input. #931
  • New: bypass_mouse_reporting_modifiers to specify which modifier(s) override application mouse reporting mode.
  • Fixed: focus tracking events are now also generated when switching between panes #941
  • New: window_frame option to configure Wayland window decorations #761
  • New: window:get_appearance() to determine if the window has a dark mode appearance, and adjust color scheme to match #806
  • Improved: improve the new-tab button formatting. Thanks to @sdrik! #950
  • Fixed: if a line of text was exactly the width of the terminal it would get marked as wrappable even when followed by a newline, causing text to reflow incorrectly on resize. #971
  • Fixed: wezterm ssh could loop forever in the background if the connection drops and the window is closed. #857
  • Improved: VT102 conformance. Many thanks to Autumn Lamonte! #904
  • New: text_blink_rate and text_blink_rate_rapid options to control blinking text. Thanks to Autumn Lamonte! #904
  • New: Added support for Synchronized Rendering #882
  • New: wezterm now draws its own pixel-perfect versions of more block drawing glyphs. See custom_block_glyphs for more details. #584
  • Fixed: wayland: CursorNotFound error with the whiteglass theme. #532
  • Improved: Can now recover from exhausting available texture space by clearing the screen. #879
  • Updated bundled Noto Color Emoji font to version 2.028 featuring a design update. Thanks to @4cm4k1! #1003
  • Fixed: wayland: putting a window in the Sway scratchpad no longer blocks the wezterm process #884
  • Fixed: mouse reporting now correctly reports release events when multiple buttons are pressed and released at the same time. #973
  • Fixed: incorrect initial window/pty size when running with some tiling window managers. #695
  • New: CTRL-SHIFT-L shows the debug overlay, which shows the error log and a lua repl. #641
  • Fixed: macOS: bright window padding on Intel-based macs #653, #716 and #1000
  • Improved: wezterm now uses the Dual Source Blending feature of OpenGL to manage subpixel anti-aliasing alpha blending, resulting in improved appearance particularly when using a transparent window over the top of something with a light background. #932
  • Fixed: copying really long lines could falsely introduce line breaks on line wrap boundaries #874
  • New: wezterm.add_to_config_reload_watch_list function to aid with automatically reloading the config when you've split your config across multiple files. Thanks to @AusCyberman! #989
  • Improved: wezterm now respects default emoji presentation and explicit emoji variation selectors (VS15 and VS16) so that glyphs that have both textual (usually monochrome, single cell width) and emoji (color, double width) presentations can be more faithfully rendered. #997
  • New: window_background_gradient option to configure color gradients for your window background
  • New: wezterm.gradient_colors function to compute RGB values for gradients for use in your config.
  • New: color schemes: Abernathy, Ayu Mirage, darkmatrix, Fairyfloss, GitHub Dark, HaX0R_BLUE, HaX0R_GR33N, HaX0R_R3D, Mariana, matrix, Peppermint and UltraDark

20210502-154244-3f7122cb

  • Fixed: red and blue subpixel channels were swapped, leading to excessively blurry text when using freetype_load_flags="HorizontalLcd". #639
  • Fixed: the selection wouldn't always clear when the intersecting lines change #644
  • Fixed: vertical alignment issue with Iosevka on Windows #661
  • Fixed: support for "Variable" fonts such as Cascadia Code and Inconsolata on all platforms #655
  • New: wezterm.font and wezterm.font_with_fallback attributes parameter now allows matching more granular font weights and font stretch. e.g.: wezterm.font('Iosevka Term', {stretch="Expanded", weight="Regular"}), as fallback can specify weight/stretch/style for each individual font in the fallback.
  • New: freetype_render_target option for additional control over glyph rasterization.
  • Fixed: wezterm ssh HOST no longer overrides the User config specified by ~/.ssh/config
  • Fixed: X11: detect when gnome DPI scaling changes #667
  • Fixed: potential panic when pasting large amounts of multi-byte text #668
  • Fixed: X11: non-ascii text could appear mangled in titlebars #673
  • Improved font IO performance and memory usage on all platforms
  • New window:toast_notification method for showing desktop notifications. #619
  • Fixed: half-pixel gaps in ligatured/double-wide glyphs depending on the font size #614
  • Fixed: Window could vanish if a tab closed while the rightmost tab was active(!) #690
  • Fixed: macOS: mouse cursor could get stuck in the hidden state. #618
  • Improved: font_rules behavior to always append reasonable default font_rules to those that you may have specified in your config. font_rules now also include defaults for half-bright text styles.
  • Improved: added use_cap_height_to_scale_fallback_fonts option to scale secondary fonts according to relative their cap-height metric to improve size consistency. This partially applies to some symbol/emoji fonts, but is dependent upon the font having reliable metrics.
  • Improved: font-config queries now run much faster, resulting in snappier startup on unix systems
  • Fixed: Hide had no effect on macOS when the titlebar was disabled #679
  • Fixed: key and mouse assignments set via window:set_config_overrides were not respected. #656
  • Fixed: potential panic when word selecting off top of viewport #713
  • Fixed: really long busy wait when displaying single logical json line of 1.5MB in length #714
  • New: swallow_mouse_click_on_pane_focus option #724
  • New: pane_focus_follows_mouse option #600
  • Fixed: splitting a pane while a pane is in the zoomed state would swallow the new pane #723
  • Fixed: multi-cell glyphs weren't displayed in tab titles #711
  • New: format-window-title hook for customizing the text in the window titlebar
  • New: format-tab-title hook for customizing the text in tab titles. #647
  • Removed: active and inactive tab_bar_style config values; use the new format-tab-title event instead
  • New: force_reverse_video_cursor setting to override the cursor color scheme settings. #706
  • Fixed: ssh config parsing now expands ~ to your home directory for appropriate options; previously only %d and ${HOME} were substituted. #729
  • New: Quick Select Mode for a tmux-fingers/tmux-thumbs style mouse-less select and copy flow #732
  • Fixed: tabs would remain hovered after moving the mouse down into the main terminal area #591
  • New: tab_bar_at_bottom setting to put the tab bar at the bottom of the window #278
  • New: wezterm.column_width function for measuring the displayed width of a string
  • New: wezterm.pad_left, wwezterm.pad_right, wezterm.truncate_left and wezterm.truncate_right function for truncating/padding a string based on its displayed width
  • Updated bundled Noto Color Emoji font to version 2.020 with unicode 13.1 support. Thanks to @4cm4k1! #742
  • Fixed: Numpad Enter reported as CTRL-C on macOS #739
  • Fixed: mouse reporting button state not cleared when focus is lost, eg: from clicking a link #744
  • Improved: better looking curly underline. Thanks to @ModProg! #733
  • Fixed: wezterm now sets argv0 to -$SHELL to invoke a login shell, rather than running $SHELL -l. #753
  • Improved: ssh_config parsing now supports Match for Host, LocalUser.
  • Improved render performance for wide windows #740
  • New color schemes: Aurora, BlueDolphin, BlulocoDark, BlulocoLight, Doom Peacock, Galizur, Guezwhoz, PaleNightHC, Raycast_Dark, Raycast_Light, Sublette, iceberg-dark and iceberg-light.

20210405-110924-a5bb5be8

  • Fixed: bold text got broken as part of fixing #617 :-( #648

20210404-112810-b63a949d

  • Fixed: 100% CPU due to spurious resize events generated by herbstluftwm. #557
  • Fixed: improved conformance with xterm for keys like CTRL-6 and CTRL-/. #556
  • Fixed: detection and handling of fonts such as terminus-bold.otb that contain only bitmap strikes. #560
  • Fixed: the pixel size reported by the pty to the kernel wasn't adjusted for font metrics/dpi until the config was reloaded or window resized. #563
  • Fixed: greatly reduce memory consumption when system fallback fonts are loaded #559
  • Fixed: Windows: window_background_opacity was only taking effect when window_decorations="NONE" #553
  • Fixed: an issue where wezterm could hang if the process spawned by a pane doesn't quit when asked #558
  • Fixed: panic when dismissing the tab navigator #542
  • Fixed: font fallback on macOS returns unresolvable .AppleSymbolsFB rather than Apple Symbols, leading to slowdowns when rendering symbols #506
  • Fixed: laggy repaints for large windows particularly on Windows, but applicable to all systems. Tuned and triple-buffered vertex buffer updates. #546
  • Changed: allow_square_glyphs_to_overflow_width now defaults to WhenFollowedBySpace and applies to more symbol glyphs. #565
  • Changed: macOS: CMD-Q is now bound by default to QuitApplication
  • New: added skip_close_confirmation_for_processes_named option which specifies a list of processes for which it is considered safe to allow closing a pane/tab/window without a prompt. #562
  • Fixed: triggering the search overlay again while the search overlay is active no longer closes the underlying pane #572
  • Fixed: X10 mouse coordinate reporting encoding could produce invalid outputs for large windows. Capped coordinate values to the maximum value that is representable in UTF-8 encoding
  • Fixed: font fallback now happens asynchronously from painting #508
  • New: added window:get_selection_text_for_pane method #575
  • Fixed: implicit hyperlink rules, word and line selection now operate on logical lines which means that they deal with wrapped lines outside of the viewport. #408
  • New: wezterm ssh now supports reading ~/.ssh/config and overriding options via the command line. IdentityFile and ProxyCommand are the two main new supported options. Read more about it in ssh.
  • Fixed: ssh support will now try all available identities from the SSH agent rather than just the first.
  • New: splitting panes in wezterm ssh now works like spawning new tabs: the new program is started on the remote host with no additional authentication required.
  • Fixed: Multiplexer sessions would fail to bootstrap via ssh because the bootstrap process exited too soon. #507
  • Fixed: Windows: we now compile libssh2 against openssl on all platforms to improve overall key and crypto algorithm support
  • Fixed: spawning a new tab via the launcher menu failed because it used the pretty printed multiplexer domain label rather than the multiplexer domain name.
  • Fixed: macOS: middle mouse button wasn't recognized. Thanks to @guswynn! #599
  • New: added ActivateLastTab key assignment for jumping back to a previously active tab. Thanks to @alexgartrell #610
  • Fixed: added missing XTSMGRAPHICS query/response for sixel support #609
  • Fixed: avoid showing an error dialog for synthesized font_rules when the configuration specifies a font that doesn't have bold/italic variants. #617
  • New: mouse cursor hides when keyboard input is sent to a pane, and shows again when the mouse is moved. #618
  • Fixed: macOS: CTRL-Tab key combination was not recognized. #630
  • Fixed: wezterm-mux-server will now continue running even after all tabs/panes have been closed. #631
  • Fixed: macOS: wezterm-gui could linger in the background until the mouse moves after all tabs/panes have closed
  • Fixed: when using line_height, wezterm now vertically centers the cell rather than padding only the top #582
  • Fixed: macOS: in US layouts, SUPER+SHIFT+[ was incorrectly recognized as SUPER+SHIFT+{ instead of SUPER+{ #601
  • Fixed: wezterm.config_dir was returning the config file path instead of the directory!
  • New: wezterm.config_file which returns the config file path

20210314-114017-04b7cedd

  • New: tab_bar_style allows customizing the appearance of the rest of tha tab bar.
  • New: animated gif and png images displayed via wezterm imgcat (the iTerm2 image protocol), or attached to the window background via window_background_image will now animate while the window has focus.
  • New: added foreground_text_hsb setting to adjust hue, saturation and brightness when text is rendered.
  • New: added ResetFontAndWindowSize key assignment.
  • New: added ScrollByLine key assignment.
  • New: OSC 777 and OSC 9 escapes now generate Toast Notifications. printf "\e]777;notify;%s;%s\e\\" "title" "body" and printf "\e]9;%s\e\\" "hello there". These don't currently pass through multiplexer connections. #489.
  • New: exit_behavior config option to keep panes open after the program has completed. #499
  • New: added --config name=value options to wezterm, wezterm-gui and wezterm-mux-server. The --front-end, --font-locator, --font-rasterizer and --font-shaper CLI options have been removed in favor of this new mechanism.
  • New: window:set_config_overrides method that can be used to override GUI related configuration options on a per-window basis. Click through to see examples of dynamically toggling ligatures and window opacity. #469 #329
  • New: introduced custom_block_glyphs option to ensure that block glyphs don't have gaps. #433
  • New: you can now drag the wezterm window via the tab bar
  • New: holding SUPER+Drag (or CTRL+SHIFT+Drag) will drag the wezterm window. Use StartWindowDrag to configure your own binding.
  • New: configure window_decorations to remove the title bar and/or window border
  • New: we now bundle PowerlineExtraSymbols as a built-in fallback font, so that you can use powerline glyphs with any font without patching the font.
  • New: window:set_right_status allows setting additional status information in the tab bar. #500
  • New: Search Mode: Added CTRL-u key assignment to clear the current search pattern. Thanks to @bew! #465
  • Fonts: font_antialias and font_hinting are now deprecated in favor of the new freetype_load_target and freetype_load_flags options. The deprecated options have no effect and will be removed in a future release. The new options provide more direct control over how freetype rasterizes text.
  • Fonts: when computing default font_rules for bold and italic fonts, strip italic and bold components from the family name. eg: if you set font = wezterm.font("Source Code Pro Medium") then the Medium text will be stripped from the font name used to locate bold and italic variants so that we don't report an error loading a non-sensical Source Code Pro Medium Bold. #456
  • Fonts: fix a regression where bright windows behind wezterm could "shine through" on the alpha channel, and adjust the tinting operation to avoid anti-aliased dark fringes #470 #491
  • Fonts: macOS: fix an issue where wezterm could hang when loading a font located via Core Text #475
  • Fonts: Changed the default font_size to 12 points. #517
  • Fonts: Updated bundled JetBrainsMono font to version 2.225
  • Added --config-file CLI option to specify an alternate config file location. Read more about config file resolution. Thanks to @bew! #459
  • OSC 52 (Clipboard manipulation) now respects the difference between PRIMARY and CLIPBOARD on X11 systems.
  • Fixed an issue where large pastes could result in a hang
  • Closing the configuration error window no longer requires confirmation
  • Fixed: an issue where the window would be redrawn on mouse move. This was most noticeable as a laggy mouse pointer when moving the mouse across a window running on the nouveau display driver on X11 and Wayland systems
  • Fixed: an issue where closing a pane would immediately SIGKILL the associated process, rather than sending SIGHUP. Thanks to @bew!
  • Fixed: line-based mouse selection (default: triple click) now extends forwards to include wrapped lines. #466
  • Fixed: the RIS escape wasn't clearing the scrollback. #511
  • Wayland: fixed opengl context creation issues. Thanks to @valpackett! #481
  • Wayland: the raw key modifiers are now correctly propagated so that they activate when used with key assignments using the key = "raw:123" binding syntax.
  • Wayland: fixed window decoration and full screen handling #224
  • Wayland: fixed an issue where key repeat processing could "run away" and hang the application
  • Windows: the portable .zip file download now includes ANGLE EGL, just like the setup.exe installer has done since version 20201031-154415-9614e117
  • Windows: Fixed ToggleFullScreen so that it once again toggles between full screen and normal placement. #177
  • Windows: fix the unexpected default behavior of Ctrl-Alt being converted to AltGr for layouts supporting this key, the previous behavior is still possible by enabling the option treat_left_ctrlalt_as_altgr (to solve #392). Thanks to @bew! #512
  • Windows: fixed "Open WezTerm Here" context menu in explorer when used on the root of a drive (eg: C:\). Thanks to @flyxyz123! #526 #451
  • X11: fix an issue where SHIFT-Enter was not recognized #516
  • X11: improved DPI detection for high-DPI displays. #515
  • X11: we now load the XCursor themes when possible, which means that the mouse cursor is now generally a bit larger and clearer as well as conforming more with the prevailing style of the desktop environment. #524
  • Improved and optimized image processing so that watching videos via timg - Terminal Image and Video Viewer works better #537 #535 #534

20210203-095643-70a364eb

  • Fix cursor position after using iTerm2 image protocol #317
  • Fix pixel dimensions after changing the pane size; this was mostly invisible but impacted image scaling when using sixel or iTerm2 image protocols. #312
  • Add support for OSC 133 which allows annotating output as Output, Input (that you typed) and Prompt (shell "chrome"). Learn more about Semantic prompt and OSC 133
  • Add ScrollToPrompt key assignment that scrolls the viewport to the prior/next shell prompt emitted using OSC 133 Semantic Prompt escapes. This assignment is not bound by default.
  • Fixed an issue where SpawnWindow didn't use the current working directory from the current pane to spawn the new window
  • Added wezterm start --class CLASSNAME option to specify the window class name under X11 and Windows, or the app_id under Wayland. See wezterm start --help for more information.
  • Added shell integration for setting OSC 7 (working directory) and OSC 133 (semantic zones) for Zsh and Bash. See Shell Integration docs.
  • Added SemanticZone as a possible parameter for SelectTextAtMouseCursor, making it possible to conveniently select complete input or output regions.
  • Improved font rendering #320 #331 #413 and changed font_antialias = "Greyscale" by default.
  • Updated internal harfbuzz shaper to 2.7.2
  • Fixed ALT-Escape not sending ESC-ESC #338
  • Added allow_square_glyphs_to_overflow_width = "WhenFollowedBySpace" option to allow square symbol glyphs to deliberately overflow their specified cell width when the next cell is a space. Can be set to Always to allow overflowing regardless of the next cell being a space, or Never to strictly respect the cell width. The default is Never. #342
  • macOS: Improved key input when Option is pressed. Fixed dead key processing when use_ime=true. #357
  • macOS: Adjusted default dpi to 72 to bring point sizes into alignment with other macOS apps. #332
  • Improved font fallback; we now try harder to find a system-provided font for glyphs that are not found in your explicitly configured fonts.
  • Revised pty output processing and removed the related ratelimit_output_bytes_per_second option
  • Workaround Cocoa leaking window position saved state file descriptors to child processes on macOS Big Sur, and Gnome/Mutter doing something similar under X11
  • The 256 color cube now uses slightly brighter colors #348
  • New: added line_height configuration option to scale the computed cell height. The default is 1.0, resulting in using the font-specified metrics. Setting it to 1.2 will result in a 20% larger cell height.
  • macOS: Fixed an issue where hovering over the split between panes could result in wezterm becoming unresponsive #391
  • Closing windows and QuitApplication will now prompt for confirmation before proceeding with the close/quit. Added window_close_confirmation to control this; valid values are AlwaysPrompt and NeverPrompt. #280
  • Tidied up logging. Previously ERROR level logging was used to make sure that informational things showed up in the stderr stream. Now we use INFO level logging for this to avoid alarming the user. You can set WEZTERM_LOG=trace in the environment to get more verbose logging for troubleshooting purposes.
  • Windows: fix an issue where VNC-server-emulated AltGr was not treated as AltGr #392
  • X11: fix an issue where keys that produce unicode characters retained SHIFT as a modifier instead of normalizing it away. #394
  • Fixed an issue where a symbol-only font would be seen as 0-width and panic wezterm #404
  • Tweaked mouse selection: we now round the x-coordinate to the nearest cell which makes it a bit more forgiving if the mouse cursor is slightly to the left of the intended cell start. #350
  • Added selection_word_boundary option to control double-click word selection boundaries. The default is \t\n{}[]()"'`. #405
  • Added support for Curly, Dotted and Dashed underlines. See this documentation on the escape sequences how enable undercurl support in vim and nvim. #415
  • Fixed an issue where wezterm would spawn processes with umask 077 on unix systems, rather than the more commonly expected umask 022. #416
  • macOS: We now ship a Universal binary containing both Intel and "Apple Silicon" architectures
  • Setting a really large or really small font scale (using CTRL +/-) no longer causes a panic #428
  • Fixed an issue where the mouse wheel wasn't mapped to cursor up/down when the alternate screen was active #429
  • Fixed ToggleFullScreen not working on macOS and X11. It still doesn't function on Windows. native_macos_fullscreen_mode = false uses a fast full-screen window on macOS. Set it to true to use the slower macOS native "Spaces" style fullscreen mode. #177
  • Windows: fix an issue where the initial window size didn't factor the correct DPI when the system-wide display scaling was not 100%. #427
  • New: adjust_window_size_when_changing_font_size option to control whether changing the font size adjusts the dimensions of the window (true) or adjusts the number of terminal rows/columns (false). The default is true. #431
  • macOS: we no longer use MetalANGLE to render the gui; it was short lived as macOS Big Sur now uses Metal in its CGL implementation. Support for using MetalANGLE is still present if the dylib is found on startup, but we no longer ship the dylib.
  • Windows: when pasting text, ensure that the text has CRLF line endings unless bracketed paste is enabled. This imperfect heuristic helps to keep multi-line pastes on multiple lines when using Windows console applications and to avoid interleaved blank lines when using unix applications. #411
  • New: ClearScrollback now accepts a parameter to control whether the viewport is cleared along with the scrollback. Thanks to @dfrankland!
  • New: default_cwd to specify an alternative current working directory. Thanks to @dfrankland!
  • New: CopyTo and PasteFrom actions. Copy, Paste and PastePrimarySelection are now deprecated in favor of these new options.
  • X11: Mouse-based selection now copies-to and pastes-from the PrimarySelection by default. The CompleteSelection and CompleteSelectionOrOpenLinkAtMouseCursor actions now require a parameter to specify the clipboard.
  • X11: SHIFT-CTRL-C and SHIFT-CTRL-V now copy-to and paste from the Clipboard by default. SHIFT-Insert pastes from the PrimarySelection by default.
  • New: Added a new default CTRL-Insert key assignment bound to CopyTo(PrimarySelection)
  • macOS: Windows now have drop-shadows when they are opaque. These were disabled due transparency support was added. Thanks to Rice! #445
  • Unix: adjust font-config patterns to also match "dual spacing" fonts such as Iosevka Term. Thanks to Leiser! #446
  • New: Added alternate_buffer_wheel_scroll_speed option to control how many cursor key presses are generated by the mouse wheel when the alternate screen is active. The new default for this is a faster-than-previous-releases 3 lines per wheel tick. #432
  • macOS: Dead Keys are now processed even when use_ime=false. More details in the docs. #410.
  • X11: attempt to load cursors from the XCursor.theme resource specified on the root window #524
  • Added file:// URL matching to the default list of implicit hyperlink rules #525

20201101-103216-403d002d

  • Whoops! fixed a crash on macOS when using multiple windows in the new Metal renderer #316

20201031-154415-9614e117

  • New: split/pane support! CTRL+SHIFT+ALT+" to SplitVertical, and CTRL+SHIFT+ALT+% to SplitHorizontal.
  • New: LEADER modifier key support
  • New: window_background_opacity and window_background_image options to control using background images, transparent windows. More info
  • New color schemes: Dracula+, Gruvbox Light, MaterialDarker, Overnight Slumber, Popping and Locking, Rapture, jubi, nord.
  • New: expanded lua API allows handling URI clicks and keyboard events with lua callbacks. See wezterm.on docs.
  • The GUI layer now normalizes SHIFT state for keyboard processing. If a keypress is ASCII uppercase and SHIFT is held then the SHIFT modifier is removed from the set of active modifiers. This has implications for your key assignment configuration; previously you would write {key="T", mods="CTRL|SHIFT"}, after updating to this release you need to write {key="T", mods="CTRL"} in order for your key bindings to take effect.
  • Added show_tab_index_in_tab_bar option which defaults to true. Causes the tab's ordinal index to be prefixed to tab titles. The displayed number is 1-based. You can set tab_and_split_indices_are_zero_based=true if you prefer the number to be zero based.
  • On Linux and macOS systems, wezterm can now attempt to guess the current working directory that should be set in newly spawned local panes/tabs, in case you don't have OSC 7 integration setup in your shell.
  • We now bundle JetBrains Mono and use it as the default font, and add it as a default fallback font. Similarly, we also bundle Noto Color Emoji as a default fallback for emoji.
  • Added automatically_reload_config=false option to disable automatic config reloading. When set to false, you will need to manually trigger a config reload (default: SUPER+R or CTRL+SHIFT+R)
  • CloseCurrentTab now requires a confirm parameter.
  • Halved the memory usage requirements per Cell in the common case (saving 32 bytes per cell), which gives more headroom for users with large scrollback.
  • Reduced initial GPU VRAM requirement to 2MiB. Improved texture allocation to avoid needing lots of VRAM.
  • macOS: Fix issue where new windows would open as Cocoa tabs when wezterm was maximized.
  • macOS: Fix issue where wezterm wouldn't adjust to DPI changes when dragging across monitors or the screen resolution changed
  • macOS: Reduced trackpad based scrolling sensitivity; it was hyper sensitive in previous releases, and now it is more reasonable.
  • Fix an issue where EGL failed to initialize on Linux
  • If EGL/WGL/OpenGL fail to initialize, we now try to fallback to Mesa OpenGL in software render mode. This should result in its llvmpipe renderer being used as a fallback, which has improved visuals compared to wezterm's own basic CPU based renderer. (This applies to X11/Wayland and Windows systems).
  • Setting front_end="Software" will try to use the Mesa OpenGL software renderer if available (X11/Wayland/Windows). The old basic CPU renderer has been removed.
  • The multiplexer server has been moved into its own wezterm-mux-server executable. You will need to revise your serve_command configuration.
  • Windows: when started in an RDP session, force the use of the Mesa software renderer to work around problems with RDP GPU emulation.
  • Fixed an issue with TLS Multiplexing where bootstrapping certificates would usually fail.
  • Windows: Fixed an issue that prevented ALT-Space from showing the system menu in the window.
  • Windows: Fixed dead key handling. By default dead keys behave the same as in other programs and produce diacritics. However, setting use_dead_keys = false in the config will cause dead keys to behave like a regular key; eg: ^ would just emit ^ as its own character.
  • Windows: Fixed an issue with the Hide key assignment; it would hide the window with no way to show it again! Hide now minimizes the window instead.
  • macOS: we now use Metal to render the gui, via MetalANGLE
  • Windows: we now prefer to use Direct3D11 to render the gui, via ANGLE EGL. The primary benefit of this is that upgrading your graphics drivers while you have a stateful wezterm session will no longer terminate the wezterm process. Resize behavior is not as smooth with ANGLE as the prior WGL. If you wish, you can set prefer_egl = false to use WGL.
  • Improved image protocol support to have better render fidelity and to reduce VRAM usage when the same image it displayed multiple times in the same pane.

20200909-002054-4c9af461

  • Added support for OSC 1 (Icon Title changing), and changed how that interacts with OSC 2 (Window Title changing). If you specify OSC 1 as a non-empty string, then that will be used for the title of that terminal instance in the GUI. Otherwise the Window Title will be reported instead.
  • Added missing mappings for Application Keypad keys on Linux
  • Workaround an EGL issue where Mesa reports the least-best alpha value when enumerating configs, rather than the best alpha. This could lead to incorrect alpha under XWayland and failure to initialize EGL and fallbacks to the Software renderer in some other cases.
  • enable_wayland now defaults to false; mutter keeps breaking client-side window decoration so let's just make it opt-in so that the default experience is better.
  • Fixed a crash on Linux/X11 when using wezterm connect HOST
  • Added tab_max_width config setting to limit the maximum width of tabs in the tab bar. This defaults to 16 glyphs in width.

20200718-095447-d2315640

  • Added support for DECSET 1004 Focus Reporting to local (not multiplexer) terminal sessions.
  • Added support for SGR 53/55 which enable/disable Overline style. printf "\x1b[53moverline\x1b[0m\n"
  • Windows: updated bundled openconsole.exe to efb1fdd to resolve an issue where bold text didn't respect the configured color scheme.
  • Added bold_brightens_ansi_colors option to allow disabling the automatic brightening of bold text.
  • Unix: fix an issue where setting the current working directory for a custom spawned command would not take effect (thanks @john01dav!)
  • Windows: fixed buffering/timing issue where a response to a color query in vim could be misinterpreted and replace a character in the editor with the letter g.
  • X11: Improved support for non-24bpp display depths. WezTerm now tries harder to obtain an 8bpc surface on both 16bpp and 30bpp (10bpc) displays.
  • Windows: fixed falling back to a simpler OpenGL context if WGL is unable to negotiate a robust context. This is useful on systems with dual high/low power GPU hardware where the OpenGL versions for the two GPUs are different!
  • Color Schemes: synced with ea2c841 which includes new schemes: Adventure, Banana Blueberry, Blue Matrix, BlueBerryPie, Cyberdyne, Django, DjangoRebornAgain, DjangoSmooth, DoomOne, Konsolas, Laser, Mirage, Rouge 2, Sakura, Scarlet Protocol, synthwave-everything, Tinacious Design (Dark), Tinacious Design (Light).

20200620-160318-e00b076c

  • Fixed default mapping of ambiguous ctrl key combinations (i, m, [, {, @) so that they emit the old school tab, newline, escape etc. values. These got broken as part of prototyping CSI-u support a while back.
  • Added option to enable CSI-u key encodings. This is a new mapping scheme defined here http://www.leonerd.org.uk/hacks/fixterms/ that disambiguates and otherwise enables more key binding combinations. You can enable this setting using enable_csi_u_key_encoding = true in your config file.
  • Very early support for sixel graphics
  • macos: use_ime now defaults to false; this is a better out of the box experience for most users.
  • macos: we now attempt to set a reasonable default LANG environment based on the locale settings at the time that wezterm is launched.
  • macos: introduce send_composed_key_when_left_alt_is_pressed and send_composed_key_when_right_alt_is_pressed boolean config settings. Like the existing send_composed_key_when_alt_is_pressed option, these control whether the Alt or Option modifier produce composed output or generate the raw key position with the ALT modifier applied. The difference from the existing config option is that on systems where Left and Right Alt can be distinguished you now have the ability to control this behavior independently. The default behavior on these systems is send_composed_key_when_left_alt_is_pressed=false and send_composed_key_when_right_alt_is_pressed=true so that the right Alt key behaves more like an AltGr key and generates the composed input, while the Left Alt is regular uncomposed Alt.
  • Fonts: fixed an issue where specifying italic or bold in the second parameter of wezterm.font didn't work as intended or documented
  • Improved terminal emulation conformance; added left/right margin support and now passes esctest to a similar degree as iTerm2
  • Fixed an issue where unmodified F5+ would use the CSI-u encoded-modifiers format, and confused eg: htop.
  • ActivateTab now accepts negative numbers as a way to reference the last tab in the Window. The default assignment for CTRL+SHIFT+9 and CMD+9 is now ActivateTab=-1, which selects the last tab.
  • Fixed an issue when applying hyperlink rules to lines that had mixed width characters

20200607-144723-74889cd4

  • Windows: Fixed AltGr handling for European layouts
  • X11: Added PastePrimarySelection key assignment that pastes the contents of the primary selection rather than the clipboard.
  • Removed old TOML config file parsing code
  • Removed old arg="something" key binding parameter. This was a remnant from the TOML based configuration. You're unlikely to notice this unless you followed an example from the docs; migrate instead to using eg: action=wezterm.action{ActivateTab=i-1} to pass the integer argument.
  • Windows: now also available with a setup.exe installer. The installer enables "Open WezTerm Here" in the explorer.exe context menu.
  • Added ClearScrollback key assignment to clear the scrollback. This is bound to CMD-K and CTRL-SHIFT-K by default.
  • Added Search key assignment to search the scrollback. Read the new scrollback section for more information!
  • Fixed an issue where ALT+number would send the wrong output for European keyboard layouts on macOS and Linux. As part of this the default behavior has changed: we used to force ALT+number to produce ALT+number instead of the composed key for that layout. We now emit the composed key by default. You can switch to the old behavior either by explicitly binding those keys or by setting send_composed_key_when_alt_is_pressed = false in your configuration file.
  • Windows: the launcher menu now automatically lists out any WSL environments you have installed so that you can quickly spawn a shell in any of them. You can suppress this behavior if you wish by setting add_wsl_distributions_to_launch_menu = false. Read more about the launcher menu
  • Added ActivateCopyMode key assignment to put the tab into mouseless-copy mode; use the keyboard to define the selected text region. This is bound to CTRL-SHIFT-X by default.

20200517-122836-92c201c6

  • AppImage: Support looking for configuration in WezTerm.AppImage.config and WezTerm.AppImage.home to support portable thumbdrive use of wezterm on linux systems
  • We now check the github releases section for updated stable releases and show a simple UI to let you know about the update, with links to download/install it. We don't automatically download the release: just make a small REST API call to github. There is no data collection performed by the wezterm project as part of this. We check once every 24 hours. You can set check_for_updates = false in your config to disable this completely if desired, or set check_for_updates_interval_seconds to an alternative update interval.
  • Added support for OSC 110-119 to reset dynamic colors, improving our support for Neovim.
  • Change OSC rendering to use the long-form ST sequence ESC \ rather than the more convenient alternative BEL representation, which was not recognized by Neovim when querying for color information.
  • Fixed Shift-Tab key on X11 and Wayland
  • WezTerm is now also available to Windows users via Scoop

20200503-171512-b13ef15f

  • Added the launch_menu configuration for the launcher menu as described in Launching Programs.
  • Fixed a crash when reloading a config with enable_tab_bar=false
  • Fixed missing icon when running under X11 and Wayland
  • Wayland client-side-decorations improved and now also render window title
  • Implicitly SGR reset when switching alt and primary screen
  • Improved config error reporting UI: we now show just a single window with all errors rather than one window per failed reload.

20200406-151651-5b700e4

  • Added lua based configuration. Reading TOML configuration will be rapidly phased out in favor of the more flexible lua config; for now, both are supported, but new features may not be available via TOML.
  • Added launcher overlay. Right click the + button on the tab bar or bind a key to ShowLauncher to activate it. It allows spawning tabs in various domains as well as attaching multiplexer sessions that were not connected automatically at startup.
  • Windows: we now support mouse reporting on Windows native ptys. For this to work, conpty.dll and OpenConsole.exe must be present alongside wezterm.exe when starting wezterm.
  • Added initial_rows and initial_cols config options to set the starting size of new terminal windows
  • Added hide_tab_bar_if_only_one_tab = true config option to hide the tab bar when the window contains only a single tab.
  • Added HideApplication key action (defaults to CMD-H on macOS only) which hides the wezterm application. This is macOS specific.
  • Added QuitApplication key action which causes the gui loop to terminate and the application to exit. This is not bound by default, but you may choose to assign it to something like CMD-Q.
  • Added set_environment_variables configuration section to allow defining some environment variables to be passed to your shell.
  • Improved connectivity UI that shows ssh and mux connection progress/status
  • Fixed a bug where the baud rate was not applied when opening a serial port
  • Added predictive local echo to the multiplexer for higher latency connections
  • We now grey out the UI for lagging multiplexer connections
  • Set an upper bound on the memory usage for multiplexer connections

20200202-181957-765184e5

  • Improved font shaping performance 2-3x by adding a shaper cache
  • Windows: now has support for TLS based multiplexer connections
  • Multiplexer: TLS multiplexer can now be bootstrapped via SSH, and automatically manages certificates
  • Unix: We now default to spawning shells with the -l argument to request a login shell. This is important on macOS where the default GUI environment doesn't source a working PATH from the shell, resulting in an anemic PATH unless the user has taken care to cover this in their shell startup. -l works to enable a login shell in zsh, bash, fish and tcsh. If it doesn't work with your shell, you can use the default_prog configuration option to override this.
  • We now accept rgb:XX/XX/XX color syntax for OSC 4 and related escape sequences; previously only #XXXXXX and named colors were accepted.
  • We now accept OSC 104 to reset custom colors to their defaults.
  • Added Tab Navigator overlay for folks that hoard tabs; it presents an interactive UI for selecting and activating a tab from a vertically oriented list. This is bound to Alt-9 by default.
  • Added support for DEC Origin Mode (DECOM) which improves cursor positioning with some applications
  • Added support for DEC AutoWrap Mode (DECAWM) which was previously always on. This improves rendering for applications that explicitly disable it.
  • We now show a connection status window while establishing MUX and SSH connections. The status window is also where any interactive authentication is carried out for eg: SSH sessions.
  • Improved SSH authentication handling; we now give you a few opportunities to authenticate and are now able to successfully authenticate with sites that have configured 2-Factor authentication in their server side SSH configuration.
  • Fixed an issue where SHIFT-Space would swallow the space key.
  • Nightly builds are now available for Linux in AppImage format.
  • Shift+Left Mouse button can now be used to extend the selection to the clicked location. This is particularly helpful when you want to select something that is larger than the viewport.
  • Windows: a single mouse wheel tick now scrolls by the number of positions configured in the Windows system settings (default 3)
  • Windows: fixed IME position when the tab bar is enabled
  • Windows: removed support for WinPty, which was too difficult to obtain, configure and use.
  • Configuration errors now show in a separate window on startup, or when the configuration is reloaded
  • Improved reliability and performance of MUX sessions, although they still have room for further improvement

20200113-214446-bb6251f

  • Added color_scheme configuration option and more than 200 color schemes
  • Improved resize behavior; lines that were split due to the width of the terminal are now rewrapped on resize. Issue 14
  • Double-click and triple-click and hold followed by a drag now extends the selection by word and line respectively.
  • The OSC 7 (CurrentWorkingDirectory) escape sequence is now supported; wezterm records the cwd in a tab and that will be used to set the working directory when spawning new tabs in the same domain. You will need to configure your shell to emit OSC 7 when appropriate.
  • Changed Backspace/Delete handling
  • Added MoveTabRelative for changing the ordering of tabs within a window using key assignments CTRL+SHIFT+PageUp and CTRL+SHIFT+PageDown
  • The multiplexer protocol is undergoing major changes. The multiplexer will now raise an error if the client and server are incompatible.
  • Fixed an issue where wezterm would linger for a few seconds after the last tab was closed
  • Fixed an issue where wezterm wouldn't repaint the screen after a tab was closed
  • Clicking the OS window close button in the titlebar now closes the window rather than the active tab
  • Added use_ime option to optionally disable the use of the IME on macOS. You might consider enabling this if you don't like the way that the IME swallows key repeats for some keys.
  • Fix an issue where the pidfile would leak into child processes and block restarting the mux server
  • Fix an issue where the title bars of remote tabs were not picked up at domain attach time
  • Fixed selection and scrollbar position for multiplexer tabs
  • Added ScrollByPage key assignment and moved the SHIFT+PageUp handling up to the gui layer so that it can be rebound.
  • X11: a single mouse wheel tick now scrolls by 5 rows rather than 1
  • Wayland: normalize line endings to unix line endings when pasting
  • Windows: fixed handling of focus related messages, which impacted both the appearance of the text cursor and copy and paste handling.
  • When hovering over implicitly hyperlinked items, we no longer show the underline for every other URL with the same destination

20191229-193639-e7aa2f3

  • Fixed a hang when using middle mouse button to paste
  • Recognize 8-bit C1 codes encoded as UTF-8, which are used in the Fedora 31 bash prexec notification for gnome terminal
  • Ensure that underlines are a minimum of 1 pixel tall
  • Reduced CPU utilization on some Wayland compositors
  • Added $WEZTERM_CONFIG_FILE to the start of the config file search path
  • Added new font rendering options:
font_antialias = "Subpixel" # None, Greyscale, Subpixel
font_hinting = "Full" # None, Vertical, VerticalSubpixel, Full
  • Early startup errors now generate a "toast" notification, giving you more of a clue about what went wrong
  • We now use the default configuration if the config file had errors, rather than refusing to start
  • Wayland compositors: Improved detection of display scaling on startup
  • Added harfbuzz_features option to specify stylistic sets for fonts such as Fira Code, and to control various typographical options
  • Added a window_padding config section to add padding to the window display
  • We now respect DECSCUSR and DECTCEM escape sequence to select between hidden, block, underline and bar cursor types, as well as blinking cursors. New configuration options have been added to control the appearance and blink rate.
  • We now support an optional basic scroll bar. The scroll bar occupies the right window padding and has a configurable color. Scroll bars are not yet supported for multiplexer connections and remain disabled by default for the moment.
  • Color scheme changes made in the config file now take effect at config reload time for all tabs that have not applied a dynamic color scheme.

20191218-101156-bf35707

  • Configuration errors detected during config loading are now shown as a system notification
  • New font_dirs configuration option to specify a set of dirs to search for fonts. Useful for self-contained wezterm deployments.
  • The font_system option has been split into font_locator, font_shaper and font_rasterizer options.
  • Don't allow child processes to inherit open font files on posix systems!
  • Disable Nagle's algorithm for wezterm ssh sessions
  • Add native Wayland window system support

20191124-233250-cb9fd7d

  • New tab bar UI displays tabs and allows creating new tabs
  • Configuration file changes are hot reloaded and take effect automatically on save
  • wezterm ssh user@host for ad-hoc SSH sessions. You may also define SSH multiplexer sessions.
  • wezterm serial /dev/ttyUSB0 to connect to your Arduino
  • wezterm imgcat /some/image.png to display images inline in the terminal using the iTerm2 image protocol
  • IME support on macOS and Windows systems
  • Automatic fallback to software rendering if no GPU is available (eg: certain types of remote desktop sessions)

Configuration Files

wezterm will look for a lua configuration file using the logic shown below.

The recommendation is to place your configuration file at $HOME/.wezterm.lua to get started.

More complex configurations that need to span multiple files can be placed in $XDG_CONFIG_HOME/wezterm/wezterm.lua (for X11/Wayland) or $HOME/.config/wezterm/wezterm.lua (for all other systems).

graph TD
  X[Locate Configuration file] --> A{{--config-file CLI argument specified?}}
  A -->|Yes| B{{Can that file be loaded?}}
  B -->|Yes| C[Use it]
  B -->|No| D[Use built-in default configuration]
  A -->|No| E{{$WEZTERM_CONFIG_FILE<br/>environment set?}}
  E -->|Yes| B
  E -->|No| F{{"Running on Windows and<br/>wezterm.lua exists in same<br/>dir as wezterm.exe?<br/>(Thumb drive mode)"}}
  F -->|Yes| B
  F -->|No| H{{Is $XDG_CONFIG_HOME<br/>environment set and<br/>wezterm/wezterm.lua<br/>exists inside it?}}
  H -->|Yes| B
  J --> B
  H -->|No| K{{Does $HOME/.config/wezterm/wezterm.lua exist?}}
  K -->|Yes| B
  K -->|No| J[Use $HOME/.wezterm.lua]

Prior to version 20210314-114017-04b7cedd, if the candidate file exists but failed to parse, wezterm would treat it as though it didn't exist and continue to try other candidate file locations. In all current versions of wezterm, an error will be shown and the default configuration will be used instead.

Note that on Windows, to support users that carry their wezterm application and configuration around on a thumb drive, wezterm will look for the config file in the same location as wezterm.exe. That is shown in the chart above as thumb drive mode.

wezterm will watch the config file that it loads; if/when it changes, the configuration will be automatically reloaded and the majority of options will take effect immediately. You may also use the CTRL+SHIFT+R keyboard shortcut to force the configuration to be reloaded.

The configuration file may be evaluated multiple times for each wezterm process both at startup and in response to the configuration file being reloaded. You should avoid taking actions in the main flow of the config file that have side effects; for example, unconditionally launching background processes can result in many of them being spawned over time if you launch many copies of wezterm, or are frequently reloading your config file.

Configuration Overrides

since: 20210314-114017-04b7cedd

wezterm allows overriding configuration values via the command line; here are a couple of examples:

$ wezterm --config enable_scroll_bar=true
$ wezterm --config 'exit_behavior="Hold"'

Configuration specified via the command line will always override the values provided by the configuration file, even if the configuration file is reloaded.

Each window can have an additional set of window-specific overrides applied to it by code in your configuration file. That's useful for eg: setting transparency or any other arbitrary option on a per-window basis. Read the window:set_config_overrides documentation for more information and examples of how to use that functionality.

Configuration File Structure

The wezterm.lua configuration file is a lua script which allows for a high degree of flexibility. The script is expected to return a configuration table, so a basic empty configuration file will look like this:

return {}

Throughout these docs you'll find configuration fragments that demonstrate configuration and that look something like this:

return {
  color_scheme = 'Batman',
}

and perhaps another one like this:

local wezterm = require 'wezterm'
return {
  font = wezterm.font 'JetBrains Mono',
}

If you wanted to use both of these in the same file, you would merge them together like this:

local wezterm = require 'wezterm'
return {
  font = wezterm.font 'JetBrains Mono',
  color_scheme = 'Batman',
}

Launching Programs

By default, when opening new tabs or windows, your shell will be spawned.

Your shell is determined by the following rules:

On Posix Systems

  1. The value of the $SHELL environment variable is used if it is set
  2. Otherwise, it will resolve your current uid and try to look up your shell from the password database.

wezterm will spawn the shell and pass -l as an argument to request a login shell. A login shell generally loads additional startup files and sets up more environment than a non-login shell.

Since: 20210502-154244-3f7122cb: instead of passing -l to the shell, wezterm will spawn the shell as -$SHELL to invoke it as a login shell.

Note: if you have recently changed your shell using chsh and you have $SHELL set in the environment, you will need to sign out and sign back in again for the environment to pick up your new $SHELL value.

Since: 20220903-194523-3bb1ed61: wezterm will now always resolve the shell via the password database.

On Windows Systems

  1. The value of the %COMSPEC% environment variable is used if it is set.
  2. Otherwise, cmd.exe

Changing the default program

If you'd like wezterm to run a different program than the shell as described above, you can use the default_prog config setting to specify the argument array; the array allows specifying the program and arguments portably:

return {
  -- Spawn a fish shell in login mode
  default_prog = { '/usr/local/bin/fish', '-l' },
}

Launching a different program as a one off via the CLI

If you want to make a shortcut for your desktop environment that will, for example, open an editor in wezterm you can use the start subcommand to launch it. This example opens up a new terminal window running vim to edit your wezterm configuration:

wezterm start -- vim ~/.wezterm.lua

Specifying the current working directory

If you'd like wezterm to start running a program in a specific working directory you can do so via the config, CLI, and when using SpawnCommand:

  • Setting the default_cwd via the config:

    return {
  default_cwd = "/some/path",
}

  • One off program in a specific working directory via the CLI:

    wezterm start --cwd /some/path

  • The SpawnCommandInNewTab, and SpawnCommandInNewWindow key assignments, and the Launcher Menu described below all accept a SpawnCommand object that accepts an optional cwd field:

    {
  label = "List files in /some/path",
  args = {"ls", "-al"},
  cwd = "/some/path",
}

Panes/Tabs/Windows created after the first will generally try to resolve the current working directory of the current Pane, preferring a value set by OSC 7 and falling back to attempting to lookup the cwd of the current process group leader attached to a local Pane. If no cwd can be resolved, then the default_cwd will be used. If default_cwd is not specified, then the home directory of the user will be used.

See default_cwd for an easier to understand visualization.

Passing Environment variables to the spawned program

The set_environment_variables configuration setting can be used to add environment variables to the environment of the spawned program.

The behavior is to take the environment of the wezterm process and then set the specified variables for the spawned process.

return {
  set_environment_variables = {
    -- This changes the default prompt for cmd.exe to report the
    -- current directory using OSC 7, show the current time and
    -- the current directory colored in the prompt.
    prompt = '$E]7;file://localhost/$P$E\\$E[32m$T$E[0m $E[35m$P$E[36m$_$G$E[0m ',
  },
}

The Launcher Menu

The launcher menu is accessed from the new tab button in the tab bar UI; the + button to the right of the tabs. Left clicking on the button will spawn a new tab, but right clicking on it will open the launcher menu. You may also bind a key to the ShowLauncher or ShowLauncherArgs action to trigger the menu.

The launcher menu by default lists the various multiplexer domains and offers the option of connecting and spawning tabs/windows in those domains.

You can define your own entries using the launch_menu configuration setting. The snippet below adds two new entries to the menu; one that runs the top program to monitor process activity and a second one that explicitly launches the bash shell.

Each entry in launch_menu is an instance of a SpawnCommand object.

return {
  launch_menu = {
    {
      args = { 'top' },
    },
    {
      -- Optional label to show in the launcher. If omitted, a label
      -- is derived from the `args`
      label = 'Bash',
      -- The argument array to spawn.  If omitted the default program
      -- will be used as described in the documentation above
      args = { 'bash', '-l' },

      -- You can specify an alternative current working directory;
      -- if you don't specify one then a default based on the OSC 7
      -- escape sequence will be used (see the Shell Integration
      -- docs), falling back to the home directory.
      -- cwd = "/some/path"

      -- You can override environment variables just for this command
      -- by setting this here.  It has the same semantics as the main
      -- set_environment_variables configuration option described above
      -- set_environment_variables = { FOO = "bar" },
    },
  },
}
Screenshot

Here's a fancy example that will add some helpful entries to the launcher menu when running on Windows:

local wezterm = require 'wezterm'

local launch_menu = {}

if wezterm.target_triple == 'x86_64-pc-windows-msvc' then
  table.insert(launch_menu, {
    label = 'PowerShell',
    args = { 'powershell.exe', '-NoLogo' },
  })

  -- Find installed visual studio version(s) and add their compilation
  -- environment command prompts to the menu
  for _, vsvers in
    ipairs(
      wezterm.glob('Microsoft Visual Studio/20*', 'C:/Program Files (x86)')
    )
  do
    local year = vsvers:gsub('Microsoft Visual Studio/', '')
    table.insert(launch_menu, {
      label = 'x64 Native Tools VS ' .. year,
      args = {
        'cmd.exe',
        '/k',
        'C:/Program Files (x86)/'
          .. vsvers
          .. '/BuildTools/VC/Auxiliary/Build/vcvars64.bat',
      },
    })
  end
end

return {
  launch_menu = launch_menu,
}

WezTerm bundles JetBrains Mono, PowerlineExtraSymbols and Noto Color Emoji fonts and uses those for the default font configuration.

If you wish to use a different font face, then you can use the wezterm.font function to specify it:

local wezterm = require 'wezterm'

return {
  font = wezterm.font 'Fira Code',
  -- You can specify some parameters to influence the font selection;
  -- for example, this selects a Bold, Italic font variant.
  font = wezterm.font('JetBrains Mono', { weight = 'Bold', italic = true }),
}

Fallback

WezTerm allows specifying an ordered list of fonts; when resolving text into glyphs the first font in the list is consulted, and if the glyph isn't present in that font, WezTerm proceeds to the next font in the fallback list.

The default fallback includes the popular PowerlineExtraSymbols font, which means that you don't need to use specially patched fonts to use the powerline glyphs.

You can specify your own fallback; that's useful if you've got a killer monospace font, but it doesn't have glyphs for the asian script that you sometimes work with:

local wezterm = require 'wezterm'
return {
  font = wezterm.font_with_fallback {
    'Fira Code',
    'DengXian',
  },
}

WezTerm will still append its default fallback to whatever list you specify, so you needn't worry about replicating that list if you set your own fallback.

If none of the fonts in the fallback list (including WezTerm's default fallback list) contain a given glyph, then wezterm will resolve the system fallback list and try those fonts too. If a glyph cannot be resolved, wezterm will render a special "Last Resort" glyph as a placeholder. You may notice the placeholder appear momentarily and then refresh itself to the system fallback glyph on some systems.

Additional options for configuring fonts can be found elsewhere in the docs:

Troubleshooting Fonts

You may use wezterm ls-fonts to have wezterm explain information about which font files it will use for the different text styles.

It shows output like this:

$ wezterm ls-fonts
Primary font:
wezterm.font_with_fallback({
  -- /home/wez/.fonts/OperatorMonoSSmLig-Medium.otf, FontDirs
  {family="Operator Mono SSm Lig", weight="DemiLight"},

  -- /home/wez/.fonts/MaterialDesignIconsDesktop.ttf, FontDirs
  "Material Design Icons Desktop",

  -- /usr/share/fonts/jetbrains-mono-fonts/JetBrainsMono-Regular.ttf, FontConfig
  "JetBrains Mono",

  -- /usr/share/fonts/google-noto-emoji/NotoColorEmoji.ttf, FontConfig
  -- Assumed to have Emoji Presentation
  -- Pixel sizes: [128]
  "Noto Color Emoji",
})


When Intensity=Half Italic=true:
wezterm.font_with_fallback({
  -- /home/wez/.fonts/OperatorMonoSSmLig-BookItalic.otf, FontDirs
  {family="Operator Mono SSm Lig", weight=325, italic=true},

  -- /home/wez/.fonts/MaterialDesignIconsDesktop.ttf, FontDirs
  "Material Design Icons Desktop",

  -- /usr/share/fonts/jetbrains-mono-fonts/JetBrainsMono-Regular.ttf, FontConfig
  "JetBrains Mono",

  -- /usr/share/fonts/google-noto-emoji/NotoColorEmoji.ttf, FontConfig
  -- Assumed to have Emoji Presentation
  -- Pixel sizes: [128]
  "Noto Color Emoji",
})
...

You can ask wezterm to including a listing of all of the fonts on the system in a form that can be copied and pasted into the configuration file:

$ wezterm ls-fonts --list-system
<same output as above, but then:>
112 fonts found in your font_dirs + built-in fonts:
wezterm.font("Cascadia Code", {weight="ExtraLight", stretch="Normal", italic=false}) -- /home/wez/.fonts/CascadiaCode.ttf index=0 variation=1, FontDirs
wezterm.font("Cascadia Code", {weight="Light", stretch="Normal", italic=false}) -- /home/wez/.fonts/CascadiaCode.ttf index=0 variation=2, FontDirs
wezterm.font("Cascadia Code", {weight="DemiLight", stretch="Normal", italic=false}) -- /home/wez/.fonts/CascadiaCode.ttf index=0 variation=3, FontDirs
wezterm.font("Cascadia Code", {weight="Regular", stretch="Normal", italic=false}) -- /home/wez/.fonts/CascadiaCode.ttf index=0 variation=4, FontDirs
wezterm.font("Cascadia Code", {weight="DemiBold", stretch="Normal", italic=false}) -- /home/wez/.fonts/CascadiaCode.ttf index=0 variation=5, FontDirs
wezterm.font("Cascadia Code", {weight="Bold", stretch="Normal", italic=false}) -- /home/wez/.fonts/CascadiaCode.ttf index=0 variation=6, FontDirs
wezterm.font("Fira Code", {weight="Light", stretch="Normal", italic=false}) -- /home/wez/.fonts/FiraCode-Light.otf, FontDirs
wezterm.font("Fira Code", {weight="Regular", stretch="Normal", italic=false}) -- /home/wez/.fonts/FiraCode-Regular.otf, FontDirs
wezterm.font("Fira Code", {weight=450, stretch="Normal", italic=false}) -- /home/wez/.fonts/FiraCode-Retina.otf, FontDirs
wezterm.font("Fira Code", {weight="Medium", stretch="Normal", italic=false}) -- /home/wez/.fonts/FiraCode-Medium.otf, FontDirs
wezterm.font("Fira Code", {weight="Bold", stretch="Normal", italic=false}) -- /home/wez/.fonts/FiraCode-Bold.otf, FontDirs
wezterm.font("Font Awesome 5 Free", {weight="Black", stretch="Normal", italic=false}) -- /home/wez/.fonts/Font Awesome 5 Free-Solid-900.otf, FontDirs
...
690 system fonts found using FontConfig:
wezterm.font("Abyssinica SIL", {weight="Regular", stretch="Normal", italic=false}) -- /usr/share/fonts/sil-abyssinica-fonts/AbyssinicaSIL-R.ttf, FontConfig
wezterm.font("C059", {weight="Regular", stretch="Normal", italic=false}) -- /usr/share/fonts/urw-base35/C059-Bold.t1, FontConfig
wezterm.font("C059", {weight="Regular", stretch="Normal", italic=false}) -- /usr/share/fonts/urw-base35/C059-Roman.otf, FontConfig
wezterm.font("C059", {weight="Regular", stretch="Normal", italic=false}) -- /usr/share/fonts/urw-base35/C059-Roman.t1, FontConfig
wezterm.font("C059", {weight="Regular", stretch="Normal", italic=true}) -- /usr/share/fonts/urw-base35/C059-BdIta.t1, FontConfig
wezterm.font("C059", {weight="Regular", stretch="Normal", italic=true}) -- /usr/share/fonts/urw-base35/C059-Italic.otf, FontConfig
...

You may also display the shaping plan for a given text string; in this example, the a and the b are separated by a special symbol which is not present in the main font, so we expect to see a different font used for that glyph:

wezterm ls-fonts --text a🞄b
a    \u{61}       x_adv=8  glyph=29   wezterm.font("Operator Mono SSm Lig", {weight="DemiLight", stretch="Normal", italic=false})
                                      /home/wez/.fonts/OperatorMonoSSmLig-Medium.otf, FontDirs
🞄    \u{1f784}    x_adv=4  glyph=9129 wezterm.font("Symbola", {weight="Regular", stretch="SemiCondensed", italic=false})
                                      /usr/share/fonts/gdouros-symbola/Symbola.ttf, FontConfig
b    \u{62}       x_adv=8  glyph=30   wezterm.font("Operator Mono SSm Lig", {weight="DemiLight", stretch="Normal", italic=false})
                                      /home/wez/.fonts/OperatorMonoSSmLig-Medium.otf, FontDirs

Advanced Font Shaping Options

The harfbuzz_features option allows specifying the features to enable when using harfbuzz for font shaping.

There is some light documentation here: https://harfbuzz.github.io/shaping-opentype-features.html but it boils down to allowing opentype feature names to be specified using syntax similar to the CSS font-feature-settings options: https://developer.mozilla.org/en-US/docs/Web/CSS/font-feature-settings. The OpenType spec lists a number of features here: https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist

Options of likely interest will be:

If you want to disable ligatures in most fonts, then you may want to use a setting like this:

return {
  harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
}

Some fonts make available extended options via stylistic sets. If you use the Fira Code font, it lists available stylistic sets here: https://github.com/tonsky/FiraCode/wiki/How-to-enable-stylistic-sets

and you can set them in wezterm:

return {
  -- Use this for a zero with a dot rather than a line through it
  -- when using the Fira Code font
  harfbuzz_features = { 'zero' },
}

Since: 20220101-133340-7edc5b5a

You can specify harfbuzz_features on a per-font basis, rather than globally for all fonts:

local wezterm = require 'wezterm'
return {
  font = wezterm.font {
    family = 'JetBrains Mono',
    harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
  },
}

and this example disables ligatures for JetBrains Mono, but keeps the default for the other fonts in the fallback:

local wezterm = require 'wezterm'

return {
  font = wezterm.font_with_fallback {
    {
      family = 'JetBrains Mono',
      weight = 'Medium',
      harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
    },
    { family = 'Terminus', weight = 'Bold' },
    'Noto Color Emoji',
  },
}

Keyboard Concepts

wezterm allows assigning action(s) to specific key events, and comes pre-configured with a number of commonly useful assignments.

This page describes how key presses are handled and turned into actions or sent to the terminal as text.

It's important to understand these concepts when considering keyboard input; first, some operating system concepts:

  • Input Method Editor (IME) - An OS-provided service which allows for rich composition of input, often with a pop-over candidate selection window. This is commonly used for Asian input, but on some systems the IME may also be responsible for emoji input or dead keys. The IME may have multiple modes per language and those modes can be changed dynamically.
  • Keyboard Layout - An OS configuration that describes how to translate physical key button presses into inputs appropriate to the user's preferred input locale. The mapping performed by the layout is largely opaque to applications and, on most systems, can be changed dynamically.
  • Dead Key - a keyboard layout may define these modal keys which don't immediately produce output (and thus appears to be "dead"), but instead holds some state that will compose with a subsequently pressed key. Most commonly used for example in European layouts to produce accented versions of the plain latin alphabet.
  • Physical Key - a way to identify a key based on its hardware-dependent location. wezterm can refer to keys based on code they would emit if configured to use an ANSI US English keyboard layout (even if that layout is not currently active), or based on its raw scan code.
  • Mapped key - a way to identify a key after the keyboard layout has been applied by the OS.
  • Modifier - A key such as SHIFT, CTRL, CMD, ALT that can be held simultaneously while other keys are pressed. Modifier keys are special because keyboard hardware traditionally only supports those four modifiers, and that detail is ingrained into most OS input APIs.

And then some wezterm concepts:

  • Key Assignment - an action assigned to a matching key and modifier combination.
  • Key Table - a grouping of key assignments. For each window, wezterm maintains a stack of table activations, allowing for rich modal keyboard input customization

Keyboard Processing Flow

This schematic depicts the processing flow for keyboard events in wezterm:

flowchart TD
A[OS Generates a Key Event]
A --> B{{Is IME enabled?}}
B -->|Yes| C[Deliver event to IME] --> C1{{IME Response}}
B -->|No| F
C1 -->|Composed| D[Make RawKeyEvent from<br/> Composed text] --> RAW1
C1 -->|Composing| E[Render composing status]
C1 -->|Continue| F[Make RawKeyEvent] --> RAW1

RAW1{{match a phys: mapping?}}
RAW1 -->|Yes| RAWDONE1(( ))
RAW1 -->|No| RAW2{{match a raw: mapping?}}
RAW2 -->|Yes| RAWDONE1
RAW2 -->|No| RAW3{{match a mapped: mapping?}}
RAW3 -->|Yes| RAWDONE1
RAW3 -->|No| DEAD1{{Does RawKeyEvent complete a dead-key?}}

DEAD1 -->|Yes| I[Make KeyEvent from<br/>expanded dead key] --> KEY1
DEAD1 -->|No| DEAD2{{Does RawKeyEvent start a dead-key?}}
DEAD2 -->|No| J[Make KeyEvent from<br/>RawKeyEvent] --> KEY1
DEAD2 -->|Yes| DEADCOMP[Render composing status]

KEY1{{match a phys: mapping?}}
KEY1 -->|Yes| RAWDONE2(( ))
KEY1 -->|No| KEY2{{match a raw: mapping?}}
KEY2 -->|Yes| RAWDONE2
KEY2 -->|No| KEY3{{match a mapped: mapping?}}
KEY3 -->|Yes| RAWDONE2
KEY3 -->|No| M[Send key to terminal]

RAWDONE1 --> RAWDONE3[Perform assignment action]
RAWDONE2 --> RAWDONE3

Alt / Option Key Behavior & Composed Keys

The operating system has its own user selectable keymap that is sometimes at odds with old-school terminal emulation that pre-dates internationalization as a concept. WezTerm tries to behave reasonably by default, but also give you control in other situations.

Layouts with an AltGr key

If you have, for example, a European keyboard layout with an AltGr key then wezterm will respect the composition effects of AltGr produced by the system. For example, in a German keymap, AltGr < will produce |.

If your physical keyboard doesn't match the keyboard layout (eg: using a US keyboard with DEU selected in the OS), then the right hand Alt key is often re-interpreted as having the AltGr function with behavior as described above.

The left Alt will be treated as a modifier with no composition effects.

Microsoft Windows and Ctrl-Alt <-> AltGr

If you are using VNC and a keyboard layout with dead keys, then you may wish to enable treat_left_ctrlalt_as_altgr.

macOS Left and Right Option Key

since: 20200620-160318-e00b076c

The default behavior is to treat the left Option key as the Alt modifier with no composition effects, while the right Option key performs composition (making it approximately equivalent to AltGr on other operating systems).

You can control this behavior in your configuration:

return {
  send_composed_key_when_left_alt_is_pressed = false,
  send_composed_key_when_right_alt_is_pressed = true,
}

since: 20210203-095643-70a364eb

WezTerm is now able to perform dead-key expansion when use_ime = false. Dead keys are treated as composition effects, so with the default settings of send_composed_key_when_left_alt_is_pressed and send_composed_key_when_right_alt_is_pressed above, in a US layout, Left-Opt n will produce Alt N and Right-Opt n will will for a subsequent key press before generating an event; Right-Opt n SPACE will emit ~ whereas Right-Opt n n will emit ñ.

You may also set use_dead_keys = false to skip the hold state; continuing the example above, Right-Opt n will then immediately produce ~.

Input Method Editor (IME)

WezTerm has support for using the operating system Input Method Editor (IME) on some operating systems.

The use_ime docs have more information.

Dead Keys

since: 20201031-154415-9614e117

By default, if you are using a layout with dead keys (eg: US International layout, or a number of European layouts such as German or French) pressing a dead key in wezterm will "hold" the dead key until the next character is pressed, resulting in a combined character with a diacritic. For example, pressing ^ and then e will produce ê. Pressing ^ then SPACE will produce ^ on its own.

If you are a heavy user of Vi style editors then you may wish to disable dead key processing so that ^ can be used with a single keypress.

You can tell WezTerm to disable dead keys by setting this in your configuration file:

return {
  use_dead_keys = false,
}

Note that for X11 systems with use_ime=true, depending on the configured IME, the IME may handle dead key processing implicitly. There is no way for wezterm to prevent it from doing that, short of disabling the IME.

Defining Assignments for key combinations that may be composed

When a key combination produces a composed key result, wezterm will look up both the composed and uncomposed versions of the keypress in your key mappings. If either lookup matches your assignment, that will take precedence over the normal key processing.

Configuring Key Assignments

The default key table assignments can be overridden or extended using the keys section in your ~/.wezterm.lua config file. For example, you can disable a default assignment like this:

local wezterm = require 'wezterm'

return {
  keys = {
    -- Turn off the default CMD-m Hide action, allowing CMD-m to
    -- be potentially recognized and handled by the tab
    {
      key = 'm',
      mods = 'CMD',
      action = wezterm.action.DisableDefaultAssignment,
    },
  },
}

The action value can be one of the available key assignments. Every action has an example that shows how to use it.

Possible Modifier labels are:

  • SUPER, CMD, WIN - these are all equivalent: on macOS the Command key, on Windows the Windows key, on Linux this can also be the Super or Hyper key. Left and right are equivalent.
  • CTRL - The control key. Left and right are equivalent.
  • SHIFT - The shift key. Left and right are equivalent.
  • ALT, OPT, META - these are all equivalent: on macOS the Option key, on other systems the Alt or Meta key. Left and right are equivalent.
  • LEADER - a special modal modifier state managed by wezterm. See Leader Key for more information.
  • VoidSymbol - This keycode is emitted in special cases where the original function of the key has been removed. Such as in Linux and using setxkbmap. setxkbmap -option caps:none. The CapsLock will no longer function as before in all applications, instead emitting VoidSymbol.

You can combine modifiers using the | symbol (eg: "CMD|CTRL").

The key value can be one of the following keycode identifiers. Note that not all of these are meaningful on all platforms:

Hyper, Super, Meta, Cancel, Backspace, Tab, Clear, Enter, Shift, Escape, LeftShift, RightShift, Control, LeftControl, RightControl, Alt, LeftAlt, RightAlt, Menu, LeftMenu, RightMenu, Pause, CapsLock, VoidSymbol, PageUp, PageDown, End, Home, LeftArrow, RightArrow, UpArrow, DownArrow, Select, Print, Execute, PrintScreen, Insert, Delete, Help, LeftWindows, RightWindows, Applications, Sleep, Numpad0, Numpad1, Numpad2, Numpad3, Numpad4, Numpad5, Numpad6, Numpad7, Numpad8, Numpad9, Multiply, Add, Separator, Subtract, Decimal, Divide, NumLock, ScrollLock, BrowserBack, BrowserForward, BrowserRefresh, BrowserStop, BrowserSearch, BrowserFavorites, BrowserHome, VolumeMute, VolumeDown, VolumeUp, MediaNextTrack, MediaPrevTrack, MediaStop, MediaPlayPause, ApplicationLeftArrow, ApplicationRightArrow, ApplicationUpArrow, ApplicationDownArrow, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, F16, F17, F18, F19, F20, F21, F22, F23, F24.

Alternatively, a single unicode character can be specified to indicate pressing the corresponding key.

Pay attention to the case of the text that you use and the state of the SHIFT modifier, as key="A" will match

Physical vs Mapped Key Assignments

Since: 20220319-142410-0fcdea07

The key value can refer either to the physical position of a key on an ANSI US keyboard or to the post-keyboard-layout-mapped value produced by a key press.

You can explicitly assign using the physical position by adding a phys: prefix to the value, for example: key="phys:A". This will match key presses for the key that would be in the position of the A key on an ANSI US keyboard.

You can explicitly assign the mapped key by adding a mapped: prefix to the value, for example: key="mapped:a" will match a key press where the OS keyboard layout produces a, regardless of its physical position.

If you omit an explicit prefix, wezterm will assume phys: and use the physical position of the specified key.

The default key assignments listed above use phys:. In previous releases there was no physical position support and those assignments were all mapped:.

When upgrading from earlier releases, if you had {key="N", mods="CMD", ..} in your config, you will need to change it to either {key="N", mods="CMD|SHIFT", ..} or {key="mapped:N", mods="CMD", ..} in order to continue to respect the SHIFT modifier.

Since: 20220408-101518-b908e2dd

A new key_map_preference option controls how keys without an explicit phys: or mapped: prefix are treated. If key_map_preference = "Mapped" (the default), then mapped: is assumed. If key_map_preference = "Physical" then phys: is assumed.

The default key assignments will respect key_map_preference.

Raw Key Assignments

In some cases, wezterm may not know how to represent a key event in either its phys: or mapped: forms. In that case, you may wish to define an assignment in terms of the underlying operating system key code, using a raw: prefix.

Similar in concept to the phys: mapping described above, the raw: mapping is independent of the OS keyboard layout. Raw codes are hardware and windowing system dependent, so there is no portable way to list which key does what.

To discover these values, you can set debug_key_events = true and press the keys of interest.

You can specify a raw key value of 123 by using key="raw:123" in your config rather than one of the other key values.

Leader Key

Since: 20201031-154415-9614e117

A leader key is a a modal modifier key. If leader is specified in the configuration then pressing that key combination will enable a virtual LEADER modifier.

While LEADER is active, only defined key assignments that include LEADER in the mods mask will be recognized. Other keypresses will be swallowed and NOT passed through to the terminal.

LEADER stays active until a keypress is registered (whether it matches a key binding or not), or until it has been active for the duration specified by timeout_milliseconds, at which point it will automatically cancel itself.

Here's an example configuration using LEADER. In this configuration, pressing CTRL-A activates the leader key for up to 1 second (1000 milliseconds). While LEADER is active, the | key (with no other modifiers) will trigger the current pane to be split.

local wezterm = require 'wezterm'

return {
  -- timeout_milliseconds defaults to 1000 and can be omitted
  leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 },
  keys = {
    {
      key = '|',
      mods = 'LEADER|SHIFT',
      action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
    },
    -- Send "CTRL-A" to the terminal when pressing CTRL-A, CTRL-A
    {
      key = 'a',
      mods = 'LEADER|CTRL',
      action = wezterm.action.SendString '\x01',
    },
  },
}

VoidSymbol

Since: 20210814-124438-54e29167

On X11 systems, If you decide to change certain keys on the keyboard to VoidSymbol (like CapsLock), then you can utilize it as a LEADER or any other part of key bindings. The following example now uses VoidSymbol and uses CapsLock as a LEADER without it affecting the shift / capital state as long as you have setxkbmap -option caps:none configured.

local wezterm = require 'wezterm'

return {
  -- timeout_milliseconds defaults to 1000 and can be omitted
  -- for this example use `setxkbmap -option caps:none` in your terminal.
  leader = { key = 'VoidSymbol', mods = '', timeout_milliseconds = 1000 },
  keys = {
    {
      key = '|',
      mods = 'LEADER|SHIFT',
      action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
    },
    {
      key = '-',
      mods = 'LEADER',
      action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' },
    },
  },
}

Available Actions

See the KeyAssignment reference for information on available actions.

Key Tables

Since: 20220408-101518-b908e2dd

In addition to the default key table defined by the keys configuration option, wezterm supports defining additional named key tables using the key_tables configuration option.

On its own, a named table doesn't do anything, but when paired with the ActivateKeyTable action, some powerful keyboard customization is possible.

As a motivating example, let's consider working with panes. In the default config CTRL+SHIFT+ArrowKey will activate a pane in the direction of the arrow key, while CTRL+SHIFT+ALT+ArrowKey will resize a pane in the direction of the arrow key. Our goal is to avoid holding down so many keys at once, or even having to remember so many key combinations, so what we'd like to do is use CTRL-SHIFT-SPACE as a leader prefix to select between resize and activation modes, using r for resize and a for activation:

local wezterm = require 'wezterm'
local act = wezterm.action

-- Show which key table is active in the status area
wezterm.on('update-right-status', function(window, pane)
  local name = window:active_key_table()
  if name then
    name = 'TABLE: ' .. name
  end
  window:set_right_status(name or '')
end)

return {
  leader = { key = 'Space', mods = 'CTRL|SHIFT' },
  keys = {
    -- CTRL+SHIFT+Space, followed by 'r' will put us in resize-pane
    -- mode until we cancel that mode.
    {
      key = 'r',
      mods = 'LEADER',
      action = act.ActivateKeyTable {
        name = 'resize_pane',
        one_shot = false,
      },
    },

    -- CTRL+SHIFT+Space, followed by 'a' will put us in activate-pane
    -- mode until we press some other key or until 1 second (1000ms)
    -- of time elapses
    {
      key = 'a',
      mods = 'LEADER',
      action = act.ActivateKeyTable {
        name = 'activate_pane',
        timeout_milliseconds = 1000,
      },
    },
  },

  key_tables = {
    -- Defines the keys that are active in our resize-pane mode.
    -- Since we're likely to want to make multiple adjustments,
    -- we made the activation one_shot=false. We therefore need
    -- to define a key assignment for getting out of this mode.
    -- 'resize_pane' here corresponds to the name="resize_pane" in
    -- the key assignments above.
    resize_pane = {
      { key = 'LeftArrow', action = act.AdjustPaneSize { 'Left', 1 } },
      { key = 'h', action = act.AdjustPaneSize { 'Left', 1 } },

      { key = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } },
      { key = 'l', action = act.AdjustPaneSize { 'Right', 1 } },

      { key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } },
      { key = 'k', action = act.AdjustPaneSize { 'Up', 1 } },

      { key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } },
      { key = 'j', action = act.AdjustPaneSize { 'Down', 1 } },

      -- Cancel the mode by pressing escape
      { key = 'Escape', action = 'PopKeyTable' },
    },

    -- Defines the keys that are active in our activate-pane mode.
    -- 'activate_pane' here corresponds to the name="activate_pane" in
    -- the key assignments above.
    activate_pane = {
      { key = 'LeftArrow', action = act.ActivatePaneDirection 'Left' },
      { key = 'h', action = act.ActivatePaneDirection 'Left' },

      { key = 'RightArrow', action = act.ActivatePaneDirection 'Right' },
      { key = 'l', action = act.ActivatePaneDirection 'Right' },

      { key = 'UpArrow', action = act.ActivatePaneDirection 'Up' },
      { key = 'k', action = act.ActivatePaneDirection 'Up' },

      { key = 'DownArrow', action = act.ActivatePaneDirection 'Down' },
      { key = 'j', action = act.ActivatePaneDirection 'Down' },
    },
  },
}

Key Table Activation Stack

Each wezterm GUI window maintains a stack of activations, which allows you to create complex layering of keyboard customization.

The ActivateKeyTable action will push an entry to the stack, and provides one_shot and timeout_milliseconds fields to affect when/how it will pop itself from the stack, and replace_current to implicitly pop the current entry from the stack.

The PopKeyTable action will explicitly pop an entry from the stack.

The ClearKeyTableStack action will clear the entire stack.

The stack is also cleared when the configuration is reloaded, so if you're working on a complex key table setup and get stuck, you may be able to unstick yourself by re-saving your wezterm configuration to trigger a reload.

Since: 20220624-141144-bd1b7c5d

When resolving a key assignment, the top of stack is first searched for a match, and if one is not found, the next entry on the stack is searched and so on until a match is found.

In previous releases, only a single lookup was performed on the top of the stack.

The new behavior allows key table activations to effectively layer over the top of previously activated key assignments, making it a bit easier to compose key assignments.

Default Shortcut / Key Binding Assignments

The default key assignments are shown in the table below.

You may also use wezterm show-keys --lua to see the assignments in a form that you can copy and paste into your own configuration.

ModifiersKeyAction
SUPERcCopyTo="Clipboard"
SUPERvPasteFrom="Clipboard"
CTRL+SHIFTcCopyTo="Clipboard"
CTRL+SHIFTvPasteFrom="Clipboard"
CopyCopyTo="Clipboard"
PastePasteFrom="Clipboard"
CTRLInsertCopyTo="PrimarySelection" (since: 20210203-095643-70a364eb)
SHIFTInsertPasteFrom="PrimarySelection"
SUPERmHide
SUPERnSpawnWindow
CTRL+SHIFTnSpawnWindow
ALTEnterToggleFullScreen
SUPER-DecreaseFontSize
CTRL-DecreaseFontSize
SUPER=IncreaseFontSize
CTRL=IncreaseFontSize
SUPER0ResetFontSize
CTRL0ResetFontSize
SUPERtSpawnTab="CurrentPaneDomain"
CTRL+SHIFTtSpawnTab="CurrentPaneDomain"
SUPER+SHIFTTSpawnTab="DefaultDomain"
SUPERwCloseCurrentTab{confirm=true}
SUPER1ActivateTab=0
SUPER2ActivateTab=1
SUPER3ActivateTab=2
SUPER4ActivateTab=3
SUPER5ActivateTab=4
SUPER6ActivateTab=5
SUPER7ActivateTab=6
SUPER8ActivateTab=7
SUPER9ActivateTab=-1
CTRL+SHIFTwCloseCurrentTab{confirm=true}
CTRL+SHIFT1ActivateTab=0
CTRL+SHIFT2ActivateTab=1
CTRL+SHIFT3ActivateTab=2
CTRL+SHIFT4ActivateTab=3
CTRL+SHIFT5ActivateTab=4
CTRL+SHIFT6ActivateTab=5
CTRL+SHIFT7ActivateTab=6
CTRL+SHIFT8ActivateTab=7
CTRL+SHIFT9ActivateTab=-1
SUPER+SHIFT[ActivateTabRelative=-1
CTRL+SHIFTTabActivateTabRelative=-1
CTRLPageUpActivateTabRelative=-1
SUPER+SHIFT]ActivateTabRelative=1
CTRLTabActivateTabRelative=1
CTRLPageDownActivateTabRelative=1
CTRL+SHIFTPageUpMoveTabRelative=-1
CTRL+SHIFTPageDownMoveTabRelative=1
SHIFTPageUpScrollByPage=-1
SHIFTPageDownScrollByPage=1
SUPERrReloadConfiguration
CTRL+SHIFTRReloadConfiguration
SUPERhHideApplication (macOS only)
SUPERkClearScrollback="ScrollbackOnly"
CTRL+SHIFTKClearScrollback="ScrollbackOnly"
CTRL+SHIFTLShowDebugOverlay (Since: 20210814-124438-54e29167)
CTRL+SHIFTPPaneSelect (Since: 20220903-194523-3bb1ed61)
CTRL+SHIFTUCharSelect (Since: 20220903-194523-3bb1ed61)
SUPERfSearch={CaseSensitiveString=""}
CTRL+SHIFTFSearch={CaseSensitiveString=""}
CTRL+SHIFTXActivateCopyMode
CTRL+SHIFTSpaceQuickSelect (since: 20210502-130208-bff6815d)
CTRL+SHIFT+ALT"SplitVertical={domain="CurrentPaneDomain"}
CTRL+SHIFT+ALT%SplitHorizontal={domain="CurrentPaneDomain"}
CTRL+SHIFT+ALTLeftArrowAdjustPaneSize={"Left", 1}
CTRL+SHIFT+ALTRightArrowAdjustPaneSize={"Right", 1}
CTRL+SHIFT+ALTUpArrowAdjustPaneSize={"Up", 1}
CTRL+SHIFT+ALTDownArrowAdjustPaneSize={"Down", 1}
CTRL+SHIFTLeftArrowActivatePaneDirection="Left"
CTRL+SHIFTRightArrowActivatePaneDirection="Right"
CTRL+SHIFTUpArrowActivatePaneDirection="Up"
CTRL+SHIFTDownArrowActivatePaneDirection="Down"
CTRL+SHIFTZTogglePaneZoomState

If you don't want the default assignments to be registered, you can disable all of them with this configuration; if you chose to do this, you must explicitly register every binding.

return {
  disable_default_key_bindings = true,
}

Keyboard Encoding

When input that doesn't match a key assignment is processed, it is encoded into a byte stream and sent to the PTY associated with the program that is running in the active pane.

The default encoding scheme used by wezterm is xterm compatible, but there are some configuration options that can modify the encoding.

The standard xterm compatible encoding generates events for key presses (but not releases) and can represent the set of keys that existed on terminal hardware of the 1980's.

That scheme has worked well for quite some time, but has some ambiguity due to the way that the Control modifier "shifts" the ASCII representation of keypresses like Control-I to be ASCII Tab, as an example.

xterm modifyOtherKeys

Since: 20221119-145034-49b9839f

When wezterm receives the sequence CSI >4;Nm, where N is 0, 1 or 2, the keyboard encoding is changed according to modifyOtherKeys, which causes certain modified keys to be encoded as described in xterms docs, making it possible for applications to distinguish between the modified and unmodified key presses.

Note that enable_csi_u_key_encoding and allow_win32_input_mode both take precedence over this behavior.

CSI-u/fixterms/libtickit

Fix Keyboard Input on Terminals is an attempt at resolving the ambiguous encoding and doing a better job at representing more modifiers. It's not a perfect attempt as there are a number of issues with it.

You can enable support for this encoding by setting enable_csi_u_key_encoding = true, however, it is not recommended as it does change the behavior of some keys in backwards incompatible ways and there isn't a way for applications to detect or request this behavior.

See also: enable_csi_u_key_encoding.

Note that allow_win32_input_mode takes precedence over this option.

Kitty Keyboard Protocol

The Kitty terminal extended and enhanced the CSI-u based encoding scheme with its Comprehensive keyboard handling protocol.

The kitty protocol allows applications to request varying degrees of enhancement over the standard encoding scheme and also allows for more modifier keys (notably: CMD/Super/Windows) to be reported to the application.

enable_kitty_keyboard controls whether wezterm will honor the application requests to modify the keyboard encoding.

Windows

On Windows, allow_win32_input_mode defaults to true which causes wezterm to listen for an escape sequence generated by the ConPTY layer of Windows to enable Win32 Input Mode.

In this mode, key release events as well as events that can distinguish between positional (left/right) modifier keys are generated and this mode provides the best compatibility with win32 console applications such as Far Manager.

allow_win32_input_mode takes precedence over enable_csi_u_key_encoding.

Mouse bindings are configurable, and there are a number of default assignments described below.

The assignments are based around a triggering mouse event which may be combined with a set of modifier keys to produce an action.

By default applications running in the terminal don't respond to the mouse. However, applications can emit escape sequences to request mouse event tracking. When mouse event tracking is enabled, mouse events are NOT matched against the mouse assignments and are instead passed through to the application.

You can bypass the mouse reporting capture by holding down the SHIFT key; that will prevent the event from being passed to the application and allow matching it against your assignments as though the SHIFT key were not pressed.

The bypass_mouse_reporting_modifiers option allows you to specify an alternative set of modifiers to use for bypassing mouse reporting capture.

Default Mouse Assignments

Note: you can run wezterm show-keys to show the effective key and mouse assignments.

In the table below, Triple Left Down means that the left mouse button is being triple clicked and that the event matches the downstroke of the third quick consecutive press. Triple Left Up matches the subsequent release event of that triple click, so for a triple click both SelectTextAtMouseCursor="Line" and CompleteSelection will be triggered in that order.

NOTE: In the action column, act is an alias to wezterm.action (to avoid repetition).

EventModifiersAction
Triple Left DownNONEact.SelectTextAtMouseCursor("Line")
Double Left DownNONEact.SelectTextAtMouseCursor("Word")
Single Left DownNONEact.SelectTextAtMouseCursor("Cell")
Single Left DownSHIFTact.ExtendSelectionToMouseCursor("Cell")
Single Left DownALTact.SelectTextAtMouseCursor("Block") (since: 20220624-141144-bd1b7c5d)
Single Left UpSHIFTact.CompleteSelectionOrOpenLinkAtMouseCursor("PrimarySelection")
Single Left UpNONEact.CompleteSelectionOrOpenLinkAtMouseCursor("PrimarySelection")
Single Left UpALTact.CompleteSelection("PrimarySelection") (since: 20220624-141144-bd1b7c5d)
Double Left UpNONEact.CompleteSelection("PrimarySelection")
Triple Left UpNONEact.CompleteSelection("PrimarySelection")
Single Left DragNONEact.ExtendSelectionToMouseCursor("Cell")
Single Left DragALTact.ExtendSelectionToMouseCursor("Block") (since: 20220624-141144-bd1b7c5d)
Single Left DownALT+SHIFTact.ExtendSelectionToMouseCursor("Block") (since: 20220624-141144-bd1b7c5d)
Single Left UpALT+SHIFTact.CompleteSelection("PrimarySelection") (since: 20220624-141144-bd1b7c5d)
Double Left DragNONEact.ExtendSelectionToMouseCursor("Word")
Triple Left DragNONEact.ExtendSelectionToMouseCursor("Line")
Single Middle DownNONEact.PasteFrom("PrimarySelection")
Single Left DragSUPERact.StartWindowDrag (since 20210314-114017-04b7cedd)
Single Left DragCTRL+SHIFTact.StartWindowDrag (since 20210314-114017-04b7cedd)

If you don't want the default assignments to be registered, you can disable all of them with this configuration; if you chose to do this, you must explicitly register every binding.

return {
  disable_default_mouse_bindings = true,
}

Configuring Mouse Assignments

since: 20200607-144723-74889cd4

You can define mouse actions using the mouse_bindings configuration section:

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  mouse_bindings = {
    -- Right click sends "woot" to the terminal
    {
      event = { Down = { streak = 1, button = 'Right' } },
      mods = 'NONE',
      action = act.SendString 'woot',
    },

    -- Change the default click behavior so that it only selects
    -- text and doesn't open hyperlinks
    {
      event = { Up = { streak = 1, button = 'Left' } },
      mods = 'NONE',
      action = act.CompleteSelection 'PrimarySelection',
    },

    -- and make CTRL-Click open hyperlinks
    {
      event = { Up = { streak = 1, button = 'Left' } },
      mods = 'CTRL',
      action = act.OpenLinkAtMouseCursor,
    },
    -- NOTE that binding only the 'Up' event can give unexpected behaviors.
    -- Read more below on the gotcha of binding an 'Up' event only.
  },
}

Each entry in the mouse binding table can have the following fields:

  • event - the mouse event on which to trigger. Described in detail below.
  • mods - the keyboard modifier keys that must be active in order to match the event. mods have the same definition and meaning as for key assignments and are described in more detail in Configuring Key Assignments.
  • action - the action to take when this mouse binding is matched
  • mouse_reporting - an optional boolean that defaults to false. This mouse binding entry will only be considered if the current pane's mouse reporting state matches. In general, you should avoid defining assignments that have mouse_reporting=true as it will prevent the application running in the pane from receiving that mouse event. You can, of course, define these and still send your mouse event to the pane by holding down the configured mouse reporting bypass modifier key. (Since: 20220807-113146-c2fee766)
  • alt_screen - an optional field that defaults to 'Any', but that can also be set to either true or false. This mouse binding entry will only be considered if the current pane's alt screen state matches this field. Most of the default mouse assignments are defined as alt_screen='Any', a notable exception being that mouse wheel scrolling only applies when alt_screen=false, as the mouse wheel is typically mapped to arrow keys by the terminal in alt screen mode. (Since: 20220807-113146-c2fee766).

The action and mods portions are described in more detail in the key assignment information below.

The event portion has three components:

  • Whether it is a Down, Up or Drag event
  • The number of consecutive clicks within the click threshold (the click streak)
  • The mouse button; Left, Right, or Middle.

A double click is a down-up-down sequence where either the second button down is held for long enough or is released and no subsequent down event occurs within the click threshold. When recognized, it emits a Down event with streak=2. If the mouse is moved while the button is held, a Drag event with streak=2 is generated. When the mouse button is released an Up event with streak=2 is generated.

The mouse event recognizer supports an arbitrary click streak, so if you wanted quadruple-click bindings you can specify streak=4.

EventLua Representation
Triple Left Downevent={Down={streak=3, button="Left"}}
Double Left Upevent={Up={streak=2, button="Left"}}
Single Left Dragevent={Drag={streak=1, button="Left"}}

since: 20220807-113146-c2fee766

You can handle vertical wheel scroll events using the example shown below. The streak and amount associated with either WheelUp or WheelDown are set to 1 for the sake of simplicity of matching the event; you may use window:current_event, if to access the actual delta scroll value while handling the event.

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  mouse_bindings = {
    -- Scrolling up while holding CTRL increases the font size
    {
      event = { Down = { streak = 1, button = { WheelUp = 1 } } },
      mods = 'CTRL',
      action = act.IncreaseFontSize,
    },

    -- Scrolling down while holding CTRL decreases the font size
    {
      event = { Down = { streak = 1, button = { WheelDown = 1 } } },
      mods = 'CTRL',
      action = act.DecreaseFontSize,
    },
  },
}

Gotcha on binding an 'Up' event only

If you only have a mouse bind on the 'Up' event and not on the 'Down' event, the 'Down' event will still be sent to the running program. If that program is tracking mouse inputs (like tmux or vim with mouse support), you may experience unintuitive behavior as the program receives the 'Down' event, but not the 'Up' event (which is bound to something in your config).

To avoid this, it is recommended to disable the 'Down' event (to ensure it won't be sent to the running program), for example:

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  mouse_bindings = {
    -- Bind 'Up' event of CTRL-Click to open hyperlinks
    {
      event = { Up = { streak = 1, button = 'Left' } },
      mods = 'CTRL',
      action = act.OpenLinkAtMouseCursor,
    },
    -- Disable the 'Down' event of CTRL-Click to avoid weird program behaviors
    {
      event = { Down = { streak = 1, button = 'Left' } },
      mods = 'CTRL',
      action = act.Nop,
    },
  },
}

Available Actions

See the KeyAssignment reference for information on available actions.

Color Scheme

WezTerm ships with over 700 color schemes available from iTerm2-Color-Schemes, base16, Gogh and terminal.sexy and a couple of other locations.

You can select a color scheme with a line like this:

return {
  color_scheme = 'Batman',
}

You can find a list of available color schemes and screenshots in The Color Schemes Section.

Precedence of colors vs color_schemes

The color_scheme option takes precedence over the colors section below, and is mutually exclusive with it. If you want to merge/override colors you need to use wezterm.color.get_default_colors() and explicitly merge them.

Since: 20220903-194523-3bb1ed61

The behavior has been changed so that the color_scheme you have selected, if any, is used to define the colors, and then any colors you define in the colors section will override those colors.

Defining your own colors

You can specify the color palette using the colors configuration section.

You can configure colors with a section like this. In addition to specifying SVG/CSS3 color names, you can use #RRGGBB to specify a color code using the usual hex notation; eg: #000000 is equivalent to black:

return {
  colors = {
    -- The default text color
    foreground = 'silver',
    -- The default background color
    background = 'black',

    -- Overrides the cell background color when the current cell is occupied by the
    -- cursor and the cursor style is set to Block
    cursor_bg = '#52ad70',
    -- Overrides the text color when the current cell is occupied by the cursor
    cursor_fg = 'black',
    -- Specifies the border color of the cursor when the cursor style is set to Block,
    -- or the color of the vertical or horizontal bar when the cursor style is set to
    -- Bar or Underline.
    cursor_border = '#52ad70',

    -- the foreground color of selected text
    selection_fg = 'black',
    -- the background color of selected text
    selection_bg = '#fffacd',

    -- The color of the scrollbar "thumb"; the portion that represents the current viewport
    scrollbar_thumb = '#222222',

    -- The color of the split lines between panes
    split = '#444444',

    ansi = {
      'black',
      'maroon',
      'green',
      'olive',
      'navy',
      'purple',
      'teal',
      'silver',
    },
    brights = {
      'grey',
      'red',
      'lime',
      'yellow',
      'blue',
      'fuchsia',
      'aqua',
      'white',
    },

    -- Arbitrary colors of the palette in the range from 16 to 255
    indexed = { [136] = '#af8700' },

    -- Since: 20220319-142410-0fcdea07
    -- When the IME, a dead key or a leader key are being processed and are effectively
    -- holding input pending the result of input composition, change the cursor
    -- to this color to give a visual cue about the compose state.
    compose_cursor = 'orange',

    -- Colors for copy_mode and quick_select
    -- available since: 20220807-113146-c2fee766
    -- In copy_mode, the color of the active text is:
    -- 1. copy_mode_active_highlight_* if additional text was selected using the mouse
    -- 2. selection_* otherwise
    copy_mode_active_highlight_bg = { Color = '#000000' },
    -- use `AnsiColor` to specify one of the ansi color palette values
    -- (index 0-15) using one of the names "Black", "Maroon", "Green",
    --  "Olive", "Navy", "Purple", "Teal", "Silver", "Grey", "Red", "Lime",
    -- "Yellow", "Blue", "Fuchsia", "Aqua" or "White".
    copy_mode_active_highlight_fg = { AnsiColor = 'Black' },
    copy_mode_inactive_highlight_bg = { Color = '#52ad70' },
    copy_mode_inactive_highlight_fg = { AnsiColor = 'White' },

    quick_select_label_bg = { Color = 'peru' },
    quick_select_label_fg = { Color = '#ffffff' },
    quick_select_match_bg = { AnsiColor = 'Navy' },
    quick_select_match_fg = { Color = '#ffffff' },
  },
}

Since: 20220101-133340-7edc5b5a

You may specify colors in the HSL color space, if you prefer that over RGB, by using:

return {
  colors = {
    -- the first number is the hue measured in degrees with a range
    -- of 0-360.
    -- The second number is the saturation measured in percentage with
    -- a range of 0-100.
    -- The third number is the lightness measured in percentage with
    -- a range of 0-100.
    foreground = 'hsl:235 100 50',
  },
}

Since: 20220319-142410-0fcdea07

Colors now also accept the following CSS-style color specifications:

rgb(0,255,0)
rgb(0% 100% 0%)
rgb(0 255 0 / 100%)
rgba(0,255,0,1)
hsl(120,100%,50%)
hsl(120deg 100% 50%)
hsl(-240 100% 50%)
hsl(-240deg 100% 50%)
hsl(0.3333turn 100% 50%)
hsl(133.333grad 100% 50%)
hsl(2.0944rad 100% 50%)
hsla(120,100%,50%,100%)
hwb(120 0% 0%)
hwb(480deg 0% 0% / 100%)
hsv(120,100%,100%)
hsv(120deg 100% 100% / 100%)

The alpha value is ignored except when used with selection_fg and selection_bg:

return {
  colors = {
    -- Make the selection text color fully transparent.
    -- When fully transparent, the current text color will be used.
    selection_fg = 'none',
    -- Set the selection background color with alpha.
    -- When selection_bg is transparent, it will be alpha blended over
    -- the current cell background color, rather than replace it
    selection_bg = 'rgba(50% 50% 50% 50%)',
  },
}

Defining a Color Scheme in your .wezterm.lua

If you'd like to keep a couple of color schemes handy in your configuration file, rather than filling out the colors section, place it in a color_schemes section as shown below; you can then reference it using the color_scheme setting.

Color schemes names that you define in your wezterm.lua take precedence over all other color schemes.

All of the settings available from the colors section are available to use in the color_schemes sections.

return {
  color_scheme = 'Red Scheme',

  color_schemes = {
    ['Red Scheme'] = {
      background = 'red',
    },
    ['Blue Scheme'] = {
      background = 'blue',
    },
  },
}

See also wezterm.get_builtin_color_schemes() for some more advanced examples, such as picking a random color scheme, or deriving from a builting color scheme.

Defining a Color Scheme in a separate file

If you'd like to factor your color schemes out into separate files, you can create a file with a [colors] section; take a look at one of the available color schemes for an example.

It is recommended that you place your custom scheme in a directory named $HOME/.config/wezterm/colors if you're on a POSIX system.

On a Windows system, wezterm will search for schemes in a directory named colors that is in the same directory as the wezterm.exe.

If you wish to place your color scheme files in some other location, then you will need to instruct wezterm where to look for your scheme files; the color_scheme_dirs setting specifies a list of directories to be searched:

return {
  color_scheme_dirs = { '/some/path/to/my/color/schemes' },
}

Color scheme names that are defined in files in your color_scheme_dirs list take precedence over the built-in color schemes.

Dynamic Color Escape Sequences

Wezterm supports dynamically changing its color palette via escape sequences.

The dynamic-colors directory of the color scheme repo contains shell scripts that can change the color scheme immediately on the fly. This can be used in your own scripts to alter the terminal appearance programmatically:

$ git clone https://github.com/mbadolato/iTerm2-Color-Schemes.git
$ cd iTerm2-Color-Schemes/dynamic-colors
$ for scheme in *.sh ; do ; echo $scheme ; \
   bash "$scheme" ; ../tools/screenshotTable.sh; sleep 0.5; done

Tab Bar Appearance & Colors

The tab bar has two modes; the default is a native looking style, but is is also possible to enable a retro aesthetic. The configuration for the two styles is broadly similar, but there are a few different details.

Native (Fancy) Tab Bar appearance

The following options affect the fancy tab bar:

local wezterm = require 'wezterm'

return {
  window_frame = {
    -- The font used in the tab bar.
    -- Roboto Bold is the default; this font is bundled
    -- with wezterm.
    -- Whatever font is selected here, it will have the
    -- main font setting appended to it to pick up any
    -- fallback fonts you may have used there.
    font = wezterm.font { family = 'Roboto', weight = 'Bold' },

    -- The size of the font in the tab bar.
    -- Default to 10. on Windows but 12.0 on other systems
    font_size = 12.0,

    -- The overall background color of the tab bar when
    -- the window is focused
    active_titlebar_bg = '#333333',

    -- The overall background color of the tab bar when
    -- the window is not focused
    inactive_titlebar_bg = '#333333',
  },

  colors = {
    tab_bar = {
      -- The color of the inactive tab bar edge/divider
      inactive_tab_edge = '#575757',
    },
  },
}

In addition, the tab bar colors mentioned below also apply to the items displayed in the tab bar.

Retro Tab Bar appearance

The following options control the appearance of the tab bar:

return {
  colors = {
    tab_bar = {
      -- The color of the strip that goes along the top of the window
      -- (does not apply when fancy tab bar is in use)
      background = '#0b0022',

      -- The active tab is the one that has focus in the window
      active_tab = {
        -- The color of the background area for the tab
        bg_color = '#2b2042',
        -- The color of the text for the tab
        fg_color = '#c0c0c0',

        -- Specify whether you want "Half", "Normal" or "Bold" intensity for the
        -- label shown for this tab.
        -- The default is "Normal"
        intensity = 'Normal',

        -- Specify whether you want "None", "Single" or "Double" underline for
        -- label shown for this tab.
        -- The default is "None"
        underline = 'None',

        -- Specify whether you want the text to be italic (true) or not (false)
        -- for this tab.  The default is false.
        italic = false,

        -- Specify whether you want the text to be rendered with strikethrough (true)
        -- or not for this tab.  The default is false.
        strikethrough = false,
      },

      -- Inactive tabs are the tabs that do not have focus
      inactive_tab = {
        bg_color = '#1b1032',
        fg_color = '#808080',

        -- The same options that were listed under the `active_tab` section above
        -- can also be used for `inactive_tab`.
      },

      -- You can configure some alternate styling when the mouse pointer
      -- moves over inactive tabs
      inactive_tab_hover = {
        bg_color = '#3b3052',
        fg_color = '#909090',
        italic = true,

        -- The same options that were listed under the `active_tab` section above
        -- can also be used for `inactive_tab_hover`.
      },

      -- The new tab button that let you create new tabs
      new_tab = {
        bg_color = '#1b1032',
        fg_color = '#808080',

        -- The same options that were listed under the `active_tab` section above
        -- can also be used for `new_tab`.
      },

      -- You can configure some alternate styling when the mouse pointer
      -- moves over the new tab button
      new_tab_hover = {
        bg_color = '#3b3052',
        fg_color = '#909090',
        italic = true,

        -- The same options that were listed under the `active_tab` section above
        -- can also be used for `new_tab_hover`.
      },
    },
  },
}

Window Padding

You may add padding around the edges of the terminal area.

See the window_padding docs for more info

Styling Inactive Panes

since: 20201031-154415-9614e117

To make it easier to see which pane is active, the inactive panes are dimmed and de-saturated slightly.

You can specify your own transformation to the pane colors with a hue, saturation, brightness (HSB) multipler.

In this example, inactive panes will be slightly de-saturated and dimmed; this is the default configuration:

return {
  inactive_pane_hsb = {
    saturation = 0.9,
    brightness = 0.8,
  },
}

The transform works by converting the RGB colors to HSV values and then multiplying the HSV by the numbers specified in inactive_pane_hsb.

Modifying the hue changes the hue of the color by rotating it through the color wheel. It is not as useful as the other components, but is available "for free" as part of the colorspace conversion.

Modifying the saturation can add or reduce the amount of "colorfulness". Making the value smaller can make it appear more washed out.

Modifying the brightness can be used to dim or increase the perceived amount of light.

The range of these values is 0.0 and up; they are used to multiply the existing values, so the default of 1.0 preserves the existing component, whilst 0.5 will reduce it by half, and 2.0 will double the value.

Window Background Image

Screenshot

since: 20201031-154415-9614e117

You can attach an image to the background of the wezterm window:

return {
  window_background_image = '/path/to/wallpaper.jpg',
}

If the path is a relative path then it will be expanded relative to the directory containing your wezterm.lua config file.

PNG, JPEG, GIF, BMP, ICO, TIFF, PNM, DDS, TGA and farbfeld files can be loaded. Animated GIF and PNG files will animate while the window has focus.

The image will be scaled to fit the window contents. Very large images may decrease render performance and take up VRAM from the GPU, so you may wish to resize the image file before using it.

You can optionally transform the background image by specifying a hue, saturation, brightness multiplier:

return {
  window_background_image = '/path/to/wallpaper.jpg',

  window_background_image_hsb = {
    -- Darken the background image by reducing it to 1/3rd
    brightness = 0.3,

    -- You can adjust the hue by scaling its value.
    -- a multiplier of 1.0 leaves the value unchanged.
    hue = 1.0,

    -- You can adjust the saturation also.
    saturation = 1.0,
  },
}

See Styling Inactive Panes for more information on hue, saturation, brigthness transformations.

If you'd like to have control over scaling, tiling/repeating, scrolling behavior and more, take a look at the more power background configuration option.

Window Background Gradient

Since: 20210814-124438-54e29167

See window_background_gradient for configuration information on gradients.

Window Background Opacity

since: 20201031-154415-9614e117

If your Operating System provides Compositing support then WezTerm is able to specify the alpha channel value for the background content, rendering the window background translucent (some refer to this as transparent rather than translucent) and causing the windows/desktop behind it to show through the window.

macOS, Windows and Wayland support compositing out of the box. X11 may require installing or configuring a compositing window manager. XWayland under Mutter/Wayland also works without any additional configuration.

window_background_opacity specifies the alpha channel value with floating point numbers in the range 0.0 (meaning completely translucent/transparent) through to 1.0 (meaning completely opaque).

Setting this to a value other than the default 1.0 may impact render performance.

return {
  window_background_opacity = 1.0,
}

Text Background Opacity

since: 20201031-154415-9614e117

When using a background image or background opacity, the image content can have relatively low contrast with respect to the text you are trying to read in your terminal.

The text_background_opacity setting specifies the alpha channel value to use for the background color of cells other than the default background color.

The default for this setting is 1.0, which means that the background color is fully opaque.

The range of values permitted are 0.0 (completely translucent) through to 1.0 (completely opaque).

return {
  text_background_opacity = 0.3,
}

735 Color schemes listed by first letter

3024 (base16)

Author: Jan T. Sott (http://github.com/idleberg)
Source: https://github.com/chriskempson/base16-unclaimed-schemes
Since: 20220807-113146-c2fee766
This scheme is also known as 3024 (dark) (terminal.sexy) (but that name isn't used here).

To use this scheme, add this to your config:

return {
  color_scheme = "3024 (base16)",
}

3024 (light) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "3024 (light) (terminal.sexy)",
}

3024 Day

Author: Jan T. Sott (http://github.com/idleberg)
Source: https://github.com/mbadolato/iTerm2-Color-Schemes
This scheme is also known as 3024Day (Gogh) (but that name isn't used here).

To use this scheme, add this to your config:

return {
  color_scheme = "3024 Day",
}

3024 Night

Author: Jan T. Sott (http://github.com/idleberg)
Source: https://github.com/mbadolato/iTerm2-Color-Schemes
This scheme is also known as 3024Night (Gogh) (but that name isn't used here).

To use this scheme, add this to your config:

return {
  color_scheme = "3024 Night",
}

Abernathy

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "Abernathy",
}

Aci (Gogh)

Source: https://github.com/Gogh-Co/Gogh
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Aci (Gogh)",
}

Aco (Gogh)

Source: https://github.com/Gogh-Co/Gogh
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Aco (Gogh)",
}

Adventure

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "Adventure",
}

AdventureTime

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "AdventureTime",
}

Afterglow

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "Afterglow",
}

Afterglow (Gogh)

Source: https://github.com/Gogh-Co/Gogh
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Afterglow (Gogh)",
}

aikofog (terminal.sexy)

Author: Gutterslob
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "aikofog (terminal.sexy)",
}

Alabaster

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "Alabaster",
}

AlienBlood

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "AlienBlood",
}

Andromeda

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "Andromeda",
}

Apathy (base16)

Author: Jannik Siebert (https://github.com/janniks)
Source: https://github.com/chriskempson/base16-unclaimed-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Apathy (base16)",
}

Apprentice (base16)

Author: romainl
Source: https://github.com/casonadams/base16-apprentice-scheme
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Apprentice (base16)",
}

arcoiris

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "arcoiris",
}

Argonaut

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "Argonaut",
}

Arthur

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "Arthur",
}

Ashes (base16)

Author: Jannik Siebert (https://github.com/janniks)
Source: https://github.com/chriskempson/base16-unclaimed-schemes
Since: 20220807-113146-c2fee766
This scheme is also known as Ashes (dark) (terminal.sexy) (but that name isn't used here).

To use this scheme, add this to your config:

return {
  color_scheme = "Ashes (base16)",
}

Ashes (light) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Ashes (light) (terminal.sexy)",
}

astromouse (terminal.sexy)

Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "astromouse (terminal.sexy)",
}

Atelier Cave (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Cave (base16)",
}

Atelier Cave Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Cave Light (base16)",
}

Atelier Dune (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Dune (base16)",
}

Atelier Dune Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Dune Light (base16)",
}

Atelier Estuary (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Estuary (base16)",
}

Atelier Estuary Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Estuary Light (base16)",
}

Atelier Forest (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Forest (base16)",
}

Atelier Forest Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Forest Light (base16)",
}

Atelier Heath (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Heath (base16)",
}

Atelier Heath Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Heath Light (base16)",
}

Atelier Lakeside (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Lakeside (base16)",
}

Atelier Lakeside Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Lakeside Light (base16)",
}

Atelier Plateau (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Plateau (base16)",
}

Atelier Plateau Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Plateau Light (base16)",
}

Atelier Savanna (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Savanna (base16)",
}

Atelier Savanna Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Savanna Light (base16)",
}

Atelier Seaside (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Seaside (base16)",
}

Atelier Seaside Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Seaside Light (base16)",
}

Atelier Sulphurpool (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Sulphurpool (base16)",
}

Atelier Sulphurpool Light (base16)

Author: Bram de Haan (http://atelierbramdehaan.nl)
Source: https://github.com/atelierbram/base16-atelier-schemes
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelier Sulphurpool Light (base16)",
}

Atelierdune (dark) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierdune (dark) (terminal.sexy)",
}

Atelierdune (light) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierdune (light) (terminal.sexy)",
}

Atelierforest (dark) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierforest (dark) (terminal.sexy)",
}

Atelierforest (light) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierforest (light) (terminal.sexy)",
}

Atelierheath (dark) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierheath (dark) (terminal.sexy)",
}

Atelierheath (light) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierheath (light) (terminal.sexy)",
}

Atelierlakeside (dark) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierlakeside (dark) (terminal.sexy)",
}

Atelierlakeside (light) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierlakeside (light) (terminal.sexy)",
}

Atelierseaside (dark) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierseaside (dark) (terminal.sexy)",
}

Atelierseaside (light) (terminal.sexy)

Author: Chris Kempson
Source: https://github.com/stayradiated/terminal.sexy
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atelierseaside (light) (terminal.sexy)",
}

AtelierSulphurpool

Source: https://github.com/mbadolato/iTerm2-Color-Schemes

To use this scheme, add this to your config:

return {
  color_scheme = "AtelierSulphurpool",
}

Atlas (base16)

Author: Alex Lende (https://ajlende.com)
Source: https://github.com/ajlende/base16-atlas-scheme
Since: 20220807-113146-c2fee766

To use this scheme, add this to your config:

return {
  color_scheme = "Atlas (base16)",
}

Atom