24 Home
Daniel Eklöf edited this page 1 month 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. Emojis get “cut off”
  5. Emojis get “cut in half”
  6. Nerd Fonts, Powerline, Font Awesome doesn’t work
  7. I can’t use the mouse to select text

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.

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 Nerd Fonts, Powerline, Font Awesome doesn’t work.

Nerd Fonts, Powerline, Font Awesome doesn’t work

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.

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.


  1. Can I use a fallback font for a specific Unicode range?
  2. How to configure my shell to emit the OSC 7 escape sequence?
    1. Bash and Zsh
    2. fish

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 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


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.

Alternatively, wait until the next fish release (3.2.0) or apply #7099. This only works if you leave TERM at the default value: foot.