Home/End keys not recognised inside tmux

[Terrance]

The bug

When using tmux, bare Home and End keypresses don't seem to be recognised by name. (The real terminal is Windows Terminal as xterm-256color, and outside of tmux the keys are correctly detected.)

textual keys output for various combinations inside tmux:

Key(key='\x01', character='\x01', name='\x01', is_printable=False)
Key(key='\x04', character='\x04', name='\x04', is_printable=False)
Key(key='pageup', character=None, name='pageup', is_printable=False)
Key(key='pagedown', character=None, name='pagedown', is_printable=False)
Key(key='shift+home', character=None, name='shift_home', is_printable=False)
Key(key='shift+end', character=None, name='shift_end', is_printable=False)
Key(key='shift+pageup', character=None, name='shift_pageup', is_printable=False)
Key(key='shift+pagedown', character=None, name='shift_pagedown', is_printable=False)
Key(key='ctrl+home', character=None, name='ctrl_home', is_printable=False)
Key(key='ctrl+end', character=None, name='ctrl_end', is_printable=False)
Key(key='ctrl+pageup', character=None, name='ctrl_pageup', is_printable=False)
Key(key='ctrl+pagedown', character=None, name='ctrl_pagedown', is_printable=False)
Key(key='alt+home', character=None, name='alt_home', is_printable=False)
Key(key='alt+end', character=None, name='alt_end', is_printable=False)
Key(key='alt+pageup', character=None, name='alt_pageup', is_printable=False)
Key(key='alt+pagedown', character=None, name='alt_pagedown', is_printable=False)

Key detection is the same for both 3.0.0 (used by Posting) and the latest 5.3.0.

---

Textual Diagnostics

Versions

Name	Value
Textual	3.0.0
Rich	14.0.0

Python

Name	Value
Version	3.12.11
Implementation	CPython
Compiler	GCC 15.1.1 20250425
Executable	/home/user/.local/share/pipx/venvs/posting/bin/python

Operating System

Name	Value
System	Linux
Release	6.6.87.1-microsoft-standard-WSL2
Version	#1 SMP PREEMPT_DYNAMIC Mon Apr 21 17:08:54 UTC 2025

Terminal

Name	Value
Terminal Application	tmux (3.5a)
TERM	tmux-256color
COLORTERM	truecolor
FORCE_COLOR	Not set
NO_COLOR	Not set

Rich Console options

Name	Value
size	width=273, height=54
legacy_windows	False
min_width	1
max_width	273
is_terminal	True
encoding	utf-8
max_height	54
justify	None
overflow	None
no_wrap	False
highlight	None
markup	None
height	None

[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?
• How do I center a widget in a screen?

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]

Sorry if this seems an obvious question, but just to confirm do the Home/End keys work as expected in tmux otherwise?

[Terrance]

Just double-checked bash, vim and nano (both in and out of tmux) where they're all working as expected -- I've not noticed the keys misbehaving anywhere else, and I'm pretty much always inside a tmux session in the terminal.

[TomJGooding]

I found there's even specific handling for these keys in tmux, but the results from textual keys suggest your terminal isn't sending the expected sequences.

textual/src/textual/_ansi_sequences.py

Lines 69 to 72 in 2898b2a

	"\x1b[1~": (Keys.Home,), # tmux
	"\x1b[2~": (Keys.Insert,),
	"\x1b[3~": (Keys.Delete,),
	"\x1b[4~": (Keys.End,), # tmux

What's the output if you run cat -v and then press Home and End?

[Terrance]

Outside tmux:

$ cat -v
^[[H^[[F

Inside tmux:

$ cat -v
^[[1~^[[4~

Indeed I can see they're both defined in ANSI_SEQUENCES_KEYS.

---

Also checking with Python (Home, End, Enter, Ctrl-D), outside tmux:

$ python3 -c 'import sys; print(sys.stdin.buffer.read())'
^[[H^[[F
b'\x1b[H\x1b[F\n'

Inside tmux:

$ python3 -c 'import sys; print(sys.stdin.buffer.read())'
^[[1~^[[4~
b'\x1b[1~\x1b[4~\n'

[TomJGooding]

Hm, those look like the expected sequences!

What's the output from these commands inside tmux?

tput khome | cat -v ; echo
infocmp -1 | grep -F home

[Terrance]

Inside tmux:

$ tput khome | cat -v ; echo
^[[1~

$ infocmp -1 | grep -F home
        home=\E[H,
        khome=\E[1~,

And outside:

$ tput khome | cat -v ; echo
^[OH

$ infocmp -1 | grep -F home
        home=\E[H,
        khome=\EOH,

[TomJGooding]

Sorry just one final test and then I'm afraid I am out of ideas. Could you try running tput smkx and the same test with cat -v?

[Terrance]

Same output both inside and outside after tput smkx 😕

I've also tried launching tmux without a config file in case I set something which might interfere, but no change there either.

[Terrance]

So I hooked the debugger up to try and see what's going on here -- it's not actually getting to use ANSI_SEQUENCES_KEYS because an earlier section applies:

textual/src/textual/_xterm_parser.py

Lines 326 to 333 in 2898b2a

	if (match := _re_extended_key.fullmatch(sequence)) is not None:
	number, modifiers, end = match.groups()
	number = number or 1
	if not (key := FUNCTIONAL_KEYS.get(f"{number}{end}", "")):
	try:
	key = _character_to_key(chr(int(number)))
	except Exception:
	key = chr(int(number))

FUNCTIONAL_KEYS seems to have a smaller definition of Home and End keys:

textual/src/textual/_keyboard_protocol.py

Lines 15 to 18 in 2898b2a

	"1H": "home",
	"7~": "home",
	"1F": "end",
	"8~": "end",

I've added:

    "1~": "home",
    "4~": "end",

...and that seems to correctly detect the tmux variant keys.

[github-actions]

I hope I solved your issue!

Consider sponsoring my work to continue to maintain and develop Textual.

• Will McGugan