---
title: "Keyboard Encoding - Wez's Terminal Emulator"
source: "https://wezterm.org/config/key-encoding.html"
author:
published:
created: 2026-04-17
description: "Wez's Terminal Emulator"
tags:
  - "clippings"
---
## 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: Version 20221119-145034-49b9839f*

*The functionality described in this section requires version 20221119-145034-49b9839f of wezterm, or a more recent version.*

When wezterm receives the sequence `CSI >4;Nm`, where `N` is `0`, `1` or `2`, the keyboard encoding is changed according to [modifyOtherKeys](https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys), which causes certain modified keys to be encoded as [described in xterms docs](https://invisible-island.net/xterm/modified-keys.html), making it possible for applications to distinguish between the modified and unmodified key presses.

Note that [enable\_csi\_u\_key\_encoding](https://wezterm.org/config/lua/config/enable_csi_u_key_encoding.html) and [allow\_win32\_input\_mode](https://wezterm.org/config/lua/config/allow_win32_input_mode.html) both take precedence over this behavior.

## CSI-u/fixterms/libtickit

[Fix Keyboard Input on Terminals](http://www.leonerd.org.uk/hacks/fixterms/) 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](https://sw.kovidgoyal.net/kitty/keyboard-protocol/#bugs-in-fixterms).

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](https://wezterm.org/config/lua/config/enable_csi_u_key_encoding.html).

Note that [allow\_win32\_input\_mode](https://wezterm.org/config/lua/config/allow_win32_input_mode.html) 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](https://sw.kovidgoyal.net/kitty/keyboard-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](https://wezterm.org/config/lua/config/enable_kitty_keyboard.html) controls whether wezterm will honor the application requests to modify the keyboard encoding.

## Windows

On Windows, [allow\_win32\_input\_mode](https://wezterm.org/config/lua/config/allow_win32_input_mode.html) defaults to `true` which causes wezterm to listen for an escape sequence generated by the ConPTY layer of Windows to enable [Win32 Input Mode](https://github.com/microsoft/terminal/blob/main/doc/specs/%234999%20-%20Improved%20keyboard%20handling%20in%20Conpty.md).

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](https://wezterm.org/config/lua/config/enable_csi_u_key_encoding.html).