Alt screen
Alt Screen (Mode 1049) is a DECSET/DECRST mode that switches to the alternate screen buffer with cursor save/restore, providing the standard mechanism for full-screen terminal applications.
Syntax
CSI ? 1049 h DECSET — Save cursor and switch to alternate screen
CSI ? 1049 l DECRST — Switch to normal screen and restore cursor
DECSET-mode1049 = 0x1b, "[", "?", "1", "0", "4", "9", "h" ; DECRST-mode1049 = 0x1b, "[", "?", "1", "0", "4", "9", "l" ;
Description
Mode 1049 is an XTerm extension that provides the most complete alternate screen buffer switching mechanism. It combines cursor save, screen buffer switch, and screen clearing into a single operation.
- Set — Saves the cursor position (as if DECSC were performed), switches to the alternate screen buffer, and clears the alternate screen.
- Reset — Switches back to the normal (main) screen buffer and restores the previously saved cursor position (as if DECRC were performed).
The alternate screen buffer
The terminal maintains two independent screen buffers:
- Normal (main) screen — The primary buffer with scrollback history. This is where the shell prompt and command output appear.
- Alternate screen — A secondary buffer with no scrollback history. Full-screen applications use this buffer so they do not disturb the user's scrollback.
When the alternate screen is active, all output goes to the alternate buffer. The normal screen's contents are preserved and restored when switching back.
Related modes
Several DECSET modes deal with the alternate screen, each with slightly different behavior:
| Mode | DECSET behavior | DECRST behavior |
|---|---|---|
| 47 | Switch to alt screen | Switch to normal screen |
| 1047 | Switch to alt screen | Clear alt screen, then switch to normal |
| 1049 | Save cursor, switch to alt screen, clear it | Switch to normal screen, restore cursor |
Mode 1049 is the preferred mode because it handles cursor save/restore automatically and clears the alternate screen on entry, which is the behavior most full-screen applications expect.
Common uses
Virtually all full-screen terminal applications use Mode 1049:
- Text editors (vim, nano, emacs in terminal mode)
- Pagers (less, most)
- Terminal multiplexers (tmux, screen)
- TUI frameworks (ncurses applications, Textual, Ratatui)
Well-behaved applications reset Mode 1049 before exiting so the user's previous terminal content is restored.
The alternate screen buffer typically has no scrollback. Attempting to scroll while in the alternate screen usually has no effect unless the terminal or multiplexer provides special handling (see Mode 1007 for scroll wheel translation).
Examples
printf '\e[?1049h' # Save cursor, switch to alt screen, clear it
# ... full-screen application runs here ...
printf '\e[?1049l' # Switch back to normal screen, restore cursor
# The user's previous scrollback and prompt are restored
Specifications
| Specification | Section |
|---|---|
| XTerm ctlseqs | — |
Terminal support
| Terminal | Support | Version | Notes |
|---|---|---|---|
| Terminal Emulators | |||
| Alacritty | ✓ | Yes | |
| Bobcat | ✓ | 0.9.0 | Implemented in TerminalCtrl library. Alternate screen buffer is supported via History/scrollback configuration. |
| contour | ✓ | v0.3.0.198 | Implemented as DECMode::ExtendedAltScreen at primitives.h:626, handled in Terminal.cpp:2414 |
| foot | ✓ | 1.7.0 | |
| Ghostty | ✓ | v1.0.0 | |
| iTerm2 | ✓ | v20260216-nightly | Can be disabled via disableSmcupRmcup setting |
| Kitty | ✓ | Yes | |
| Konsole | ✓ | Yes | Combines cursor save, clear screen, and alternate buffer |
| mintty | ✓ | Yes | Implemented at src/termout.c:2539; can be disabled via config |
| mlterm | ✓ | rel-0_2_1 | Present since initial public release |
| PuTTY | ✓ | 0.54 | |
| Rio | ✓ | v0.1.13 | |
| rxvt-unicode | ✓ | 9.06 | Fully implemented with cursor save/restore |
| st | ✓ | 0.3 | |
| terminology | ✓ | v0.9.0 | Handles cursor save/restore and screen clearing |
| VT100 | ✗ | No | |
| VTE | ✓ | Yes | |
| WezTerm | ✓ | Yes | |
| Windows Terminal | ✓ | Yes | ASB_AlternateScreenBuffer at adaptDispatch.cpp:1873-1875 |
| xterm | ✓ | Yes | Alternate screen with cursor save/restore |
| xterm.js | ~ | 1.0.0 | Does not clear alternate buffer on switch |
| Multiplexers | |||
| cy | ✓ | Yes | |
| GNU Screen | ✓ | v.4.2.0 | Modes 47, 1047, 1049 supported; underlying functions present since v.4.0.2 |
| tmux | ✓ | 1.7 | |
| tuios | ✓ | v0.0.15 | |
| Zellij | ✓ | v0.31.2 | |
See also
- Alt Scroll — Mode 1007 — Scroll wheel translation on the alternate screen
- DECTCEM — Mode 25 — Show/hide cursor