75 Home
Daniel Eklöf edited this page 2 months ago


  1. Troubleshooting
  2. FAQ
  3. Reporting bugs


  1. Foot is not starting at all
  2. No colors in ls output
  3. Things break after I ssh into a remote machine
  4. I can’t use the mouse to select text
  5. Emojis are black-and-white
  6. Only 8 colors in Emacs
  7. Ctrl+key breaks input in Vim
  8. Fonts have different line or letter spacing compared to other terminal emulators
  9. Cut off glyphs
  10. Italic fonts are “cut off”
  11. Emojis get “cut off”
  12. Emojis get “cut in half”
  13. Nerd Fonts, Powerline, Font Awesome doesn’t work
  14. foot -e cmd does not set the window title to cmd

Foot is not starting at all

Try running foot from another terminal. Chances are it is printing an error message on stderr. If it does not, or if the error message is difficult to understand, please open an issue. Make sure to include the log output (along with all the other information described in the README) in the report, even if there aren't any obvious error messages.

Also remember to test without screen, tmux or other similar programs.

Did you just upgrade foot? Read through the CHANGELOG, and pay special attention to the Changed section.

No colors in ls output

ls depends on the environment variable LS_COLORS for color output. It is typically set by dircolors in your shell's startup files. Usually in the system global ones, e.g. /etc/bash/bashrc, /etc/bash/bash.d/<some file>.bashrc, /etc/zsh/zshrc or similar (grep is your friend!)

The problem is that dircolors wont set LS_COLORS if it does not recognize the terminal. This is to prevent garbage output on terminals that do not support SGR (color) escape sequences. Unlike most terminal applications, dircolors does not use terminfo to determine whether the terminal is color capable or not. Instead it has a builtin database.

Foot is not on that list and thus dircolors refuses to set LS_COLORS. We can work around this by changing the way dircolors is run. First, you need to find where it is run from. Use grep and search /etc. Make sure you edit the file actually loaded by your shell...

You should see something like eval $(dircolors), or possibly eval $(dircolors -b <a file>). Change that to eval $(env TERM=xterm-256color dircolors). Start a new terminal and check if LS_COLORS have been set. Depending on how your shell's startup files have been configured, you may also have to logout and login again.

There are other options as well. If the colors are loaded from a file, you can manually edit that file and add TERM foot*. Yet another option is to not use dircolors at all, but manually set LS_COLORS (in the shell startup file).

Things break after I ssh into a remote machine

You need to install foot's terminfo files on the remote machine.

This is precisely why the Arch packages are split into foot and foot-terminfo: to let users install the terminfo files only.

If the distribution on the remote machine does not provide a foot-terminfo package, you can manually copy the terminfo files. They are normally installed as /usr/share/terminfo/f/foot and /usr/share/terminfo/f/foot-direct, but the exact location may differ. Either copy these files to the corresponding location on the remote machine, to install them system wide, or to $HOME/.terminfo/f/ to install them for your user only.

Note that if the remote machine is running a very old Linux distribution, the terminfo files may not be recognized. In that case, you can copy the terminfo source file, foot.info to the remote machine and compile it there:

sed 's/@default_terminfo@/foot/g' foot.info | tic -x -e foot,foot-direct -

This will install the terminfo files to $HOME/.terminfo. See INSTALL.md for more information.

I can’t use the mouse to select text

Hold down Shift.

You are most likely in an application that grabs the mouse. In this mode, foot does not ‘consume’ mouse events itself, but passes them on to the application. The mouse cursor indicates this by turning into a pointer.

By holding Shift, your are temporarily disabling the application’s mouse grabbing. The mouse cursor indicates this by turning into a caret.

Emojis are black-and-white

See How do I get colored emojis?

Only 8 colors in Emacs

Emacs determines terminal capabilities by:

  • querying terminfo capabilities
  • issuing terminal queries
  • looking at the name of the terminfo

The last point is the reason Emacs by default only has 8 colors in foot. We need to tell Emacs that foot is an XTerm compatible terminal. The easiest way to do that is to add the following to your .emacs:

(add-to-list 'term-file-aliases '("foot" . "xterm"))

M-x list-colors-display should now list all 256 colors.

You may also want to enable 24-bit color support.

Ctrl+key breaks input in Vim

Pressing Ctrl+some key breaks other Ctrl+key bindings.

This is a known vim issue: https://github.com/vim/vim/issues/9014.

On foot >= 1.10.0, you can workaround this by adding the following to your vimrc:

let &t_TI = "\<Esc>[>4;2m"
let &t_TE = "\<Esc>[>4m"

Note: there are no workarounds for older versions of foot.

Fonts have different line or letter spacing compared to other terminal emulators

Try to adjust the line-height, letter-spacing, or letter-offset options in foot.ini. The first two options control the height and width, respectively, of individual cells, while letter-offset sets the starting position of a glyph inside of a cell.

Cut off glyphs

In foot < 1.8.2, glyphs were clipped. I.e. they were not allowed to overflow, or “bleed”, into the neighbouring cell.

Foot implemented heuristics to handle certain classes of Unicode code points. But things like wide italic fonts, where glyphs “lean” into the neighbouring cell, were not handled at all. These heuristics were controlled by these options (example shows their default values):


Starting in 1.8.2, all those workarounds (and configuration options) have been replaced with a new rendering technique that lets foot handle all overflowing glyphs.

Thus, “cut off” glyphs should now be a thing of the past.

If you do see cut off glyphs, that could very well be a bug, and should be reported. However, before doing so, please check that you do not have:


in your foot.ini.

Italic fonts are “cut off”

If you are on foot >= 1.8.2, see Cut off glyphs.

In versions prior to 1.8.2, glyphs from certain italic fonts can appear cut off. This happens when the font’s italic glyphs are wider than the non-italic glyphs. There is unfortunately not much to do about this, besides changing to a different font, or upgrading to 1.8.2 or later.

Emojis get “cut off”

If emojis, like 😍 get cut off, chances are you are using a narrow primary font where the width of two cells is less than the line height. Since emojis (which are double-width glyphs) are more or less square, they will get cut off.

This is easily worked around by explicitly adding your emoji font as a fallback font in foot.ini, with a custom size:

font=<your primary font>, Noto Color Emoji:size=8

Here you will have to experiment with the size. Note that you are not limited to integer sizes. I.e. size=8.5 is perfectly valid.

Emojis get “cut in half”

See Cut off glyphs

Nerd Fonts, Powerline, Font Awesome doesn’t work

(If you are on foot >= 1.8.2, see Cut off glyphs)

If you are using an “icon” font (or font collection), like Nerd Fonts, Powerline Fonts, or Font Awesome, then you will notice that the glyphs get cut in half.

The reason is these glyphs are in the Unicode Private Usage Area, PUA, and have a character width of 1. Thus, foot allocates one cell for each of these glyphs. The glyphs themselves however, are double width. Hence they get cut in half.

This also applies to some of the older emoji codepoints that were introduced into Unicode before Emojis in general.

You can enable an option in foot.ini that tries to render these glyphs without cutting them in half. They are still only allocated a single cell though, so there may be visual glitches. This should be no different from how other terminal emulators handle them however.


See #116 for the discussion that led to this solution.

Note: this is enabled by default since foot-1.5.4, and then superseded by a new rendering technique in foot 1.8.2.

foot -e cmd does not set the window title to cmd

That's expected, since foot only sets the initial window title (it never updates it after that), and the default window title is foot. There are two possible options:

Option 1: Explicitly set the initial window title using the -T,--title=TITLE flag. Example: foot --title=htop htop

Option 2: Use a wrapper script to generically set the initial window title, based on the supplied command. For the wrapper script to know which arguments are options for foot and which specify the command to run, it either needs to filter out foot's options, or the -e option has to be made mandatory for the wrapper script. Here is an example wrapper script with a mandatory -e option:

# Set foot's title to the command supplied after -e.
# Note: Option -e is mandatory for this wrapper script.

unset title
for arg; do
	if [[ "$arg" != "-e" ]]; then

if ! [[ -v title ]]; then
	printf 'error: option -e is mandatory\n'
	exit 1

exec foot --title="$title" "$@"

For possible alternative scripts, see the discussion after this comment.


  1. Shell integration
    1. Spawning new terminal instances in the current working directory
      1. Bash
      2. Zsh
      3. Fish
    2. Jumping between prompts
      1. Bash
      2. Zsh
      3. Fish
  2. Foot’s terminfo vs. ncurses’ terminfo
  3. Dynamic color changes
  4. Can I use a fallback font for a specific Unicode range?
  5. How do I get colored emojis?
  6. Enabling/disabling IME when entering/leaving insert mode in vim
  7. 24-bit color support in Emacs
  8. How do I make Ctrl+L scroll the content instead of erasing it?
    1. Bash
    2. Zsh

Shell integration

Spawning new terminal instances in the current working directory

When spawning a new terminal instance (with ctrl+shift+n by default), the new instance will start in the current working directory, if the shell in the “parent” terminal reports directory changes to foot.

This is done with the OSC-7 escape sequence. Most shells can be scripted to do this, if they do not support it natively. See examples for bash, zsh and fish below:


Add the following to your .bashrc:

osc7_cwd() {
    local strlen=${#PWD}
    local encoded=""
    local pos c o
    for (( pos=0; pos<strlen; pos++ )); do
        case "$c" in
            [-/:_.!\'\(\)~[:alnum:]] ) o="${c}" ;;
            * ) printf -v o '%%%02X' "'${c}" ;;
    printf '\e]7;file://%s%s\e\\' "${HOSTNAME}" "${encoded}"

Add the following to your .zshrc:

function osc7 {
    local LC_ALL=C
    export LC_ALL

    setopt localoptions extendedglob
    input=( ${(s::)PWD} )
    print -n "\e]7;file://${HOSTNAME}${uri}\e\\"
add-zsh-hook -Uz chpwd osc7

If you leave TERM at the default value of foot, you don't need to do anything for fish releases after 3.2.0, released 2021-03-01. Otherwise, you can apply #7099.

If using some other TERM value, add the following to ~/.config/fish/config.fish:

function update_cwd_osc --on-variable PWD --description 'Notify terminals when $PWD changes'
    if status --is-command-substitution || set -q INSIDE_EMACS
    printf \e\]7\;file://%s%s\e\\ $hostname (string escape --style=url $PWD)

update_cwd_osc # Run once since we might have inherited PWD from a parent shell

The above snippet is from functions/__fish_config_interactive.fish.

Jumping between prompts

(foot 1.13.0 and later)

To enable jumping between prompts (with ctrl+shift+z and ctrl+shift+x by default), the shell must emit an OSC-133;A sequence before each prompt.

While it would be best if the shell supported this natively, most shells do not. See below for examples on how to configure the most common shells.



prompt_marker() {
    printf '\e]133;A\e\\'

Add it to the precmd hook:

precmd() {
    print -Pn "\e]133;A\e\\"

Add an event handler for fish_prompt, in e.g. ~/.config/fish/config.fish:

function mark_prompt_start --on-event fish_prompt
    echo -en "\e]133;A\e\\"

Foot’s terminfo vs. ncurses’ terminfo

As of ncurses patch 2021-07-31, ncurses includes terminfo definitions for foot (foot and foot-direct). Yet we still provide our own version of the terminfo definitions (exact name depends on the distribution, but foot-extra and foot-extra-direct are common). Why?

One reason is to support users running foot on systems where ncurses is too old.

But another reason is that our version defines a number of non-standard capabilities, that are very unlikely to ever get upstreamed. These capabilities benefit primarily tmux, but could potentially be used by other applications as well. The non-standard capabilities we define are:

  • Sync - terminal supports application synchronized updates
  • Tc - termminal is 24-bit (True) color capable
  • setrgbb - escape sequence to use to set a 24-bit background color
  • setrgbf - escape sequence to use to set a 25-bit foreground color

It should also be noted that the initial terminfo definition in ncurses lacked the status line capabilities:

  • dsl - disable status line
  • fsl - return from status line
  • tsl - move to status line

This causes e.g. vim to not update the terminal window title.

The missing capabilities were added to ncurses in patch 2021-11-13.

Note: to get an up to date list of differences, run:

infocmp -x foot foot-extra

Replace foot-extra with whatever name your distribution uses for “our” version of the terminfo.

Dynamic color changes

Foot supports OSC4/11 which allows changing terminal colors on-the-fly. This can be used in conjunction with your shell to externally trigger color themes.

The following example is for zsh and uses the theme.sh color switcher to implement a day- and night mode.

Add the following snippet to your ~/.zshrc This adds a callback function for SIGUSR1 so that all terminals can have color schemes externally modified

  if [ "$scheme" = "night" ];then
    /path/to/theme.sh dracula
  elif [ "$scheme" = "day" ]; then
    /path/to/theme.sh belafonte-day

Issue the switch programatically by:

pkill -USR1 zsh

Can I use a fallback font for a specific Unicode range?

Yes. Since foot's font configuration uses FontConfig syntax, you can specify specific Unicode indices, or ranges, using the charset property. It is a space-separated list of hexadecimal integers, or ranges of hexadecimal integers:

<font-name>:<other-properties>:charset=37 0f00-1000 1400-1600 1782

I.e. ~/.config/foot/foot.ini may look something like:

font=Fantasque Sans Mono:size=8, Joypixels:size=7:charset=1f000-1f644

How do I get colored emojis?

Foot relies on FontConfig to locate fonts. To get colored emojis, you will have to configure FontConfig to prefer the font with colored emojis over fonts with black-and-white emojis, and over regular fonts with emoji glyphs..

One example of how this can be done (for Joypixels) is 75-joypixels.conf. To use this, copy its content to /etc/fonts/conf.avail/75-joypixels.conf (substitute with your distributions location for FontConfig configuration files), and symlink it to /etc/fonts/conf.d/75-joypixels.conf. Make sure to read the comments in it if you decide to use it.

This will of course affect other applications too.

Another option is to configure foot to use your emoji font as a fallback font in foot.ini:

font=Terminus, Joypixels

This will also allow you to tweak the size used for emojis. See Emojis get “cut off”.

Note that, regardless of which option you use, you will still get black-and-white emojis if your primary font has glyphs for emojis. See 75-joypixels.conf for ways to work around this.

Enabling/disabling IME when entering/leaving insert mode in vim

Foot implements a custom escape sequence to enable and disable IME. To hook vim’s InsertEnter and InsertLeave events to emit these escapes, add the following to your vimrc:

autocmd InsertEnter * call chansend(v:stderr, "\033[?737769h")
autocmd InsertLeave * call chansend(v:stderr, "\033[?737769l")

You may also wish to add:

set ttimeoutlen=0

to get rid of the delay when leaving insert mode.

24-bit color support in Emacs

Important: make sure Emacs has been configured to recognize foot’s terminfo.

Note: Emacs >= 28 honors the COLORTERM environment variable (which foot sets automatically), and will enable 24-bit color without needing a *-direct terminfo.

I.e. the instructions below applies to Emacs < 28.

Emacs reads terminfo capabilities to determine whether the terminal supports 24-bit colors or not. Use the foot-direct terminfo instead of foot to let Emacs know foot is 24-bit capable:

foot -t foot-direct emacs -nw

Example .desktop file that launches emacsclient inside a new footclient instance (copy to e.g. ~/.local/share/applications/emacs-terminal.desktop):

[Desktop Entry]
Name=Emacs (Terminal)
GenericName=Text Editor
Comment=Edit text
Exec=/usr/bin/footclient -t foot-direct --app-id emacs --title emacs -- emacsclient -t -a "" %F

How do I make Ctrl+L scroll the content instead of erasing it?


In some terminals, Ctrl+L scrolls the screen content instead of clearing it. Examples include VTE-based terminals, and Alacritty.

One might be led to believe that Ctrl+L sends ^L (i.e. form feed) to the terminal, which does have semantics similar to scrolling. However, this is usually not the case.

Ctrl+L is sent to the application (not the terminal itself). The application then decides what to do with it. The typical response in shells is to emit the \E[2J escape sequence. This escape does not scroll, it clears the entire screen.

In other words, scrolling the screen content on \E[2J is not correct VT100 behavior.

Recognizing the fact that scrolling, instead of clearing, on Ctrl+L can be useful, how do we implement this without breaking \E[2J?

We tell the shell to do something else when we press Ctrl+L.

The escape sequence \e[%dS was chosen for performance reasons. However, if the screen isn’t full (i.e. the prompt isn’t at the bottom of the screen) when you press Ctrl+L, the empty lines after the prompt will also be scrolled out into the scrollback.

If this isn’t acceptable, you can replace the printf in the script snippets below with this instead:

until [ $i -le 1 ]; do
    printf '\n'

This will be slower, but more accurate.


if [[ $TERM =~ ^foot ]]; then
    clear-screen-keep-sb() {
        printf '\e[%dS' $((LINES-1))
        tput -x clear
    bind -x '"\C-l":"clear-screen-keep-sb"'


if [[ $TERM =~ "^foot" ]]; then
    clear-screen-keep-sb() {
        printf "\e[$((LINES - 1))S"
        zle .clear-screen
    zle -N clear-screen clear-screen-keep-sb

Reporting bugs

Please report bugs to https://codeberg.org/dnkl/foot/issues.

Before you open a new issue, please search existing bug reports, both open and closed ones. Chances are someone else has already reported the same issue.

The report should contain the following:

  • Foot version (foot --version).
  • Log output from foot (start foot from another terminal).
  • Which Wayland compositor (and version) you are running.
  • If reporting a crash, please try to provide a bt full backtrace with symbols.
  • Steps to reproduce. The more details the better.