In this post, I want to share how to set up true color support in Tmux, Nvim and the shell to make them work nicely together.

There are tons of posts on the Internet regarding how to set up true color support to make Tmux, Nvim and terminal work together. Time flies and settings may change. There are also many people who do not really understand the reason behind all the settings and often give some ad-hoc settings. All these lead to chaos. It turns out that setting up true color support is painfully difficult and costs me several hours.

Version info

Before we begin, I will list the info about all the necessary components so that you can reproduce on your device:

  • Terminal: I use iTerm2, which supports True color by default.
  • Tmux: Version 2.7 (tmux -V) and installed with HomeBrew
  • Neovim: v0.3.1 (nvim --version) and installed with HomeBrew

First, we have to understand that not all terminal support true colors. Whether you use a terminal emulator to connect to remote host or use a native terminal, make sure that your terminal supports true colors. For a list of terminals supporting true colors, see this wonderful gists.

Setting up true color support

iTerm2 settings

For iTerm2, make sure the output of echo $TERM is xterm-256color. If the output is wrong, you should set it properly in iTerm2. Open the iTerm2 preference settings, go to Profiles --> Terminal, in the Terminal Emulation part, choose xterm-256color as the reported terminal type.

Do not set TERM variable in your shell profile! It is your terminal emulator that is responsible for reporting what kind of terminal it supports. If you set TERM variable in your shell, the TERM variable inside Tmux will also be set to that value when the shell is initialized, which is simply wrong1. Do not do this.

Neovim settings

Neovim has good support for true colors. According to official doc, to enable true color support, you need to add the following setting to init.vim:

set termguicolors

Tmux settings

In order to make Nvim colorscheme work well inside Tmux, you need to add these settings to your .tmux.conf2:

set -g default-terminal "screen-256color"
# tell Tmux that outside terminal supports true color
set -ga terminal-overrides ",xterm-256color*:Tc"

You can also use tmux-256color instead of screen-256color. Tmux-256color supports italics inside Tmux. In case your system does not have an entry for tmux-256color, you can download terminfo database and build a more complete one:

curl -LO http://invisible-island.net/datafiles/current/terminfo.src.gz
gunzip terminfo.src.gz
tic -x terminfo.src

This will install a terminfo library under your HOME in the directory .terminfo.

Verifying

Open up a Tmux session, inside Tmux, the output of echo $TERM should be screen-256color or tmux-256color depending on which term file you choose to use, but the output definitely should not be xterm-256color.

If you have set up all these properly, run the following command on the command line:

awk 'BEGIN{
    s="/\\/\\/\\/\\/\\"; s=s s s s s s s s;
    for (colnum = 0; colnum<77; colnum++) {
        r = 255-(colnum*255/76);
        g = (colnum*510/76);
        b = (colnum*255/76);
        if (g>255) g = 510-g;
        printf "\033[48;2;%d;%d;%dm", r,g,b;
        printf "\033[38;2;%d;%d;%dm", 255-r,255-g,255-b;
        printf "%s\033[0m", substr(s,colnum+1,1);
    }
    printf "\n";
}'

The above script will print a color band. If something is wrong, the color band will show obvious gradient between different parts (see image below for an example).

If everything goes well, you should be able to see a smooth color band both inside and outside Tmux.

Congratulations, you have finally got it right!

References


  1. You can find more discussion here. ↩︎

  2. If the file .tmux.conf does not exist under your HOME, just create an empty one and start editing it.. ↩︎