Terminfo

Terminfo is an archaic format still in use by many terminal applications to determine the capabilities of the terminal. Wintty ships with its own terminfo entry to advertise its features.

Wintty uses the TERM value of xterm-ghostty.

Note

Why the xterm prefix? Unfortunately, many terminal applications string search for "xterm" in the TERM value to assume capabilities. During the private beta, we experimented with a pure wintty value, but found that too many applications broke and fixing the entire ecosystem was unrealistic. We settled on xterm-ghostty to maintain compatibility.

Wintty packages include the terminfo entry and set the proper filesystem layouts or environment variables to make it available to the system. When you run Wintty, it will automatically set the TERM environment variable to xterm-ghostty so long as it detects that the terminfo entry is available.

Important

Wintty's terminfo entry is available in ncurses 6.5-20241228 and above. As distros update their ncurses packages, Wintty's terminfo entry will be available by default system-wide. This will take time to propagate.

If you use sudo, sudo may reset your environment variables and you may see an error about missing or unsuitable terminal: xterm-ghostty or 'xterm-ghostty': unknown terminal type. when running some programs.

To resolve this, you must either configure sudo to preserve the TERMINFO environment variable, or you can use shell-integration with the sudo feature enabled and Wintty will alias sudo to automatically do this for you. To enable the shell-integration feature specify shell-integration-features = sudo in your configuration.

See shell-integration-features for more about this configuration option.

If you use SSH to connect to other machines that do not have Wintty's terminfo entry, you will see error messages like missing or unsuitable terminal: xterm-ghostty, Error opening terminal: xterm-ghostty. or WARNING: terminal is not fully functional.

Hopefully someday Wintty will have terminfo entries pre-distributed everywhere, but in the meantime there are two ways to resolve the situation:

1. Copy Wintty's terminfo entry to the remote machine. The easiest way is using the following one-liner:

   infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x -
   

2. Configure SSH to fall back to a known terminfo entry using the following SSH configuration (requires OpenSSH 8.7 or newer):

   # .ssh/config
   Host example.com
     SetEnv TERM=xterm-256color
   

Both variants can be automated by Wintty's shell integration via the ssh-terminfo and ssh-env features. See SSH Integration for details, including important limitations around when the automation applies.

Note

The tic command on the server may give the warning "<stdin>", line 2, col 31, terminal 'xterm-ghostty': older tic versions may treat the description field as an alias which can be safely ignored.

Note

tic will normally place its results in the system database, /usr/share/terminfo. This location can be overridden with the TERMINFO environment variable. If TERMINFO is not set and tic cannot write to the system location, it will place the results in $HOME/.terminfo if it exists. man tic for details.

Note

macOS versions before Sonoma cannot use the system-bundled infocmp. The bundled version of ncurses is too old to emit a terminfo entry that can be read by more recent versions of tic, and the command will fail with a bunch of Illegal character messages. You can fix this by using Homebrew to install a recent version of ncurses with brew install ncurses and replacing infocmp above with the full path /opt/homebrew/opt/ncurses/bin/infocmp or /usr/local/opt/ncurses/bin/infocmp.

Warning

Fallback does not support advanced terminal features. Because xterm-256color does not include all of Wintty's capabilities, terminal features beyond xterm's like colored and styled underlines will not work.