Alt+<key> do not work

[NSPC911]

Have you checked closed issues? (https://github.com/Textualize/textual/issues?q=is%3Aissue+is%3Aclosed)

Child of #872 which is an open issue

Have you checked against the most recent version of Textual? (https://pypi.org/search/?q=textual)

yes

Consider discussions!

Issues are for actionable items only.
If Textual crashes or behaves differently from the docs, then submit an issue.
If you want to know how to do something, or you have a suggestion for a new feature, then open a discussion (https://github.com/Textualize/textual/discussions/).

For realtime help, join our discord server (https://discord.gg/Enf6Z3qhVr)

The bug

Alt key based modifiers do not register in textual, even though other CLI tools do.

> textual diagnose

Textual Diagnostics

Versions

Name	Value
Textual	6.4.0
Rich	14.2.0

Python

Name	Value
Version	3.13.8
Implementation	CPython
Compiler	MSC v.1944 64 bit (AMD64)
Executable	C:\Users\NSPG911\Git\NSPC911\rovr.venv\Scripts\python.exe

Operating System

Name	Value
System	Windows
Release	11
Version	10.0.26200

Terminal

Name	Value
Terminal Application	WezTerm (20251005-110037-db5d7437)
TERM	xterm-256color
COLORTERM	truecolor
FORCE_COLOR	Not set
NO_COLOR	Not set

Rich Console options

Name	Value
size	width=124, height=33
legacy_windows	True
min_width	1
max_width	124
is_terminal	False
encoding	cp1252
max_height	33
justify	None
overflow	None
no_wrap	False
highlight	None
markup	None
height	None

textual just doesn't seem to handle alt+ inputs, but an editor like helix can, which is weird. it can do it without the kitty keyboard protocol, and on terminals like alacritty, rio, wezterm, windows terminal and warp, which textual just isn't able to handle.

testing only wezterm, rio and warp here

2025-10-25.22-36-47.mp4

[github-actions]

We found the following entries in the FAQ which you may find helpful:

• Why do some key combinations never make it to my app?
• Why doesn't Textual support ANSI themes?
• How can I set a translucent app background?
• How can I select and copy text in a Textual app?

Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review.

This project is developed and maintained by Will McGugan. Consider sponsoring Will's work on this project (and others).

This is an automated reply, generated by FAQtory

[TomJGooding]

Just to clarify, I think alt+<key> should work in terminals that support the kitty keyboard protocol.

This includes alacritty, wezterm and rio from a quick check.

from textual.app import App, ComposeResult
from textual.widgets import Label


class ExampleApp(App):
    BINDINGS = [("alt+j", "notify('alt+j pressed')")]

    CSS = "Screen { align: center middle; }"

    def compose(self) -> ComposeResult:
        yield Label("Try pressing alt+j")


if __name__ == "__main__":
    ExampleApp().run()

[NSPC911]

i didnt say that alt keys don't work, it just isnt captured by textual itself

2025-10-31.10-58-25.mp4

[NSPC911]

@TomJGooding so I took a look at key things in Textual

1. In https://github.com/Textualize/textual/blob/main/src/textual/keys.py , there is no reference whatsoever to Alt + <key>. I don't think it is ever handled, hence the issue
2. Taking a look at the Windows and Linux drivers, Linux handles the Kitty Keyboard Protocol in https://github.com/Textualize/textual/blob/main/src/textual/drivers/linux_driver.py#L276 , but no such attempt is done in https://github.com/Textualize/textual/blob/main/src/textual/drivers/windows_driver.py
3. https://github.com/Textualize/textual/blob/main/src/textual/_ansi_sequences.py has no references to Alt + <key> as well

This means that Textual just did not at all handle Alt + <key>. It should be an oversight on Will's side.

[davep]

This means that Textual just did not at all handle Alt + .

That does then raise the question: how come I ran up textual keys, mashed a bunch of alt+ keys, and got this:

(Ghostty on macOS)

And while better handling of keys came along some time after I last had cause to dive deeply into the code, a quick look myself would have me wondering if, perhaps, my journey to understand it should start around here. Perhaps not; but I can't help but wonder if it is a reference to alt as a keyboard modifier.

[NSPC911]

a quick look myself would have me wondering if, perhaps, my journey to understand it should start around here

That is for xterm, which is for, well, the browser, I'm assuming

And anyway, yes, I have been proven wrong. I don't have access to a Mac right now, thank you.
However, this begs the question, why is Kitty Keyboard Protocol not checked for in the Windows Driver?

[davep]

That is for xterm, which is for, well, the browser, I'm assuming

I would have assumed otherwise.

$ rg "import.*XTermParser"
tests/test_xterm_parser.py
5:from textual._xterm_parser import XTermParser

src/textual/drivers/linux_driver.py
19:from textual._xterm_parser import XTermParser

src/textual/drivers/web_driver.py
27:from textual._xterm_parser import XTermParser

src/textual/drivers/linux_inline_driver.py
19:from textual._xterm_parser import XTermParser

src/textual/drivers/win32.py
13:from textual._xterm_parser import XTermParser

[NSPC911]

Okay, thanks for proving my assumption wrong.

I noticed that _xterm_parser is not imported in src/textual/drivers/windows_driver.py. I'm not exactly sure how different it is from src/textual/drivers/win32.py, but taking a look at src/textual/drivers/linux_driver.py, the linux_driver is similar to windows_driver, so win32 is more of a helper module for the windows_driver. There also appear to be some minor differences between win32's implementation and linux_driver's implementation, which is to be expected because they are two different platforms.

Anyways, at the end of the day, I'm still spitballing, I really don't know how Textual does anything this complex.

[davep]

IIRC windows_driver uses the event monitor that is found in win32, which in turn (as you can see above) uses XTermParser (that's off the top of my head though; not at a keyboard to check for sure).

[willmcgugan]

Seems we have narrowed it down to Windows. Which is helpful! Will take a look next time I boot my Windows box.

[TomJGooding]

Sorry if my reply caused some confusion here - I missed that you were running on Windows.

I've added support for the kitty keyboard protocol on Windows in #6207.

[NSPC911]

The interesting thing is that, while Alt + <key> doesn't work for most combinations, it works for Alt + <arrow key>, so things like Alt + up arrow works

[TomJGooding]

Hopefully the kitty keyboard protocol now works on Windows with the latest Textual?

---

The interesting thing is that, while Alt + <key> doesn't work for most combinations [without the kitty keyboard protocol], it works for Alt + <arrow key>

Perhaps someone with better understanding of the keyboard handling will correct me, but presumably this comes down to the sequence of bytes sent by the terminal.

For example, running showkey in WezTerm (on Linux):

$ showkey -a

Press any keys - Ctrl-D will terminate this program

^[       27 0033 0x1b    # esc
j       106 0152 0x6a    # j
^[j      27 0033 0x1b    # alt+j
        106 0152 0x6a

This shows the codes sent after pressing esc, then j, and finally alt+j. This explains what you were seeing with textual keys, since alt is output as ESC.

Whereas the output from a similar test with alt+right has a different sequence:

^[       27 0033 0x1b    # esc
^[[C     27 0033 0x1b    # right
         91 0133 0x5b
         67 0103 0x43
^[[1;3C  27 0033 0x1b    # alt+right
         91 0133 0x5b
         49 0061 0x31
         59 0073 0x3b
         51 0063 0x33
         67 0103 0x43

You might have missed the Textual handing of these keys in _ansi_sequences.py

---

TLDR: Ultimately Textual can only ever support key combinations that are passed on by your terminal. The problems with ambiguous key presses is what the kitty keyboard protocol was designed to solve.

[NSPC911]

https://discord.com/channels/1026214085173461072/1026214085865504861/1437729016441344011

kitty keyboard protocol works

ill see if i can find a showkey alternative on windows