43 Home
Daniel Eklöf edited this page 4 weeks ago


  1. Troubleshooting
  2. FAQ


  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. Fonts have different line or letter spacing compared to other terminal emulators
  8. Cut off glyphs
  9. Italic fonts are “cut off”
  10. Emojis get “cut off”
  11. Emojis get “cut in half”
  12. Nerd Fonts, Powerline, Font Awesome doesn’t work
  13. sudo: “error opening terminal” (or similar)

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 does 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=xterm256-color 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.

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.

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.

sudo: “error opening terminal” (or similar)

Foot’s terminfo definitions are (since 1.9.0) installed in a custom location (to be able to co-exist with the terminfo definitions provided by ncurses).

To let applications find it, foot exports the environment variable TERMINFO. This variable is not preserved by sudo by default, but can be told to do so. Create the file /etc/sudoers.d/foot-preserve-terminfo, with the following content:

Defaults env_keep += "TERMINFO"

and then chmod 0600 /etc/sudoers.d/foot-preserve-terminfo.


  1. Can I use a fallback font for a specific Unicode range?
  2. How do I get colored emojis?
  3. How to configure my shell to emit the OSC 7 escape sequence?
    1. Bash and Zsh
    2. fish
  4. Enabling/disabling IME when entering/leaving insert mode in vim
  5. 24-bit color support in Emacs

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 https://github.com/maximbaz/dotfiles/blob/master/packages/75-joypixels.conf. To use this, copy it to /etc/fonts/conf.avail/75-joypixels.conf, 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 https://github.com/maximbaz/dotfiles/blob/master/packages/75-joypixels.conf#L40 for ways to work around this.

How to configure my shell to emit the OSC 7 escape sequence?

Bash and Zsh

Source the following functions from your .bashrc and .zshrc:

_urlencode() {
	local length="${#1}"
	for (( i = 0; i < length; i++ )); do
		local c="${1:$i:1}"
		case $c in
			%) printf '%%%02X' "'$c" ;;
			*) printf "%s" "$c" ;;

osc7_cwd() {
	printf '\e]7;file://%s%s\e\\' "$HOSTNAME" "$(_urlencode "$PWD")"

If you use Bash, add the following to your .bashrc to run the function every time the prompt is displayed:


If you use Zsh, add the following to your .zshrc to run the function every time your working directory changes.

autoload -Uz add-zsh-hook
add-zsh-hook -Uz chpwd osc7_cwd


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.

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, "\e[?737769h")
autocmd InsertLeave * call chansend(v:stderr, "\e[?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.

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