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

There are tons of disccusions 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 know the reason behind all the settings and give some ad-hoc settings. All these lead to chaos. It turns out setting up true color support is painfully difficult and wastes 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 support 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, you have to understand that not all terminal supports true colors. Whether you use a terminal emulator to connect to remote host or use a native terminal, make sure that your terminal support true colors. For a list of terminals which support 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 configurations. 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 configuration file, the TERM variable inside Tmux will also be set to that value when the shell is initialized, which is not desired1.

Neovim settings

Neovim has a good support for true colors. According to official doc, to enable true color support, you need to use the following seting inside 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.conf file2:

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
gunzip terminfo.src.gz
tic -x terminfo.src

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


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, using 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 command will print a color band on your command line. 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!


  1. You can find more discussion here.
  2. If the file .tmux.conf does not exist under your HOME, you can create an empty one and start editting it..