There is a growing number of Vim color schemes designed to display 256 colors at the terminal. But getting this to work in some environments may require a tweak or two. This article attempts to provide a few pointers to help users set up their environment.

I only have access to i386 GNU/linux systems of the debian/ubuntu family. As far as I know the gist of this article should be relevant to other distributions or even other platforms but
I have not been able to verify it.

For clarity's sake the article does not distinguish between terminfo and termcap: they are functionally equivalent.

Contents

Download a sample color scheme (jellybeans.vim is a good choice) and copy the file to your vim/colors directory. If this directory does not exist, you will have to create it.

Check that your terminal is capable of displaying 256 colors: Fire up a terminal session and run 256colors2.pl from the shell prompt. If you get a 'command not found', you need to download the script to a directory in your PATH. The script displays the sixteen 'System Colors' as well as a 6x6x6 'Color Cube' and a 'Grey Ramp' with 24 shades of gray. Screenshots of the script's output are available online if you are in doubt about what you should be seeing.

Verify that your TERM environment variable is correctly set: A simple way to do this is to issue the 'tput colors' command at the shell prompt. If it returns '256' you are all set.

Open a couple of files (such as a C program, a python script, some html, or even your vimrc) in Vim and issue a ':color jellybeans'. You should immediately see the difference with the default color scheme.

If you like the look of jellybeans and you want to make it your default color scheme all you need to do now is add the 'color jellybeans' command to your vimrc.

Important reminder: Generally speaking, pointing to a terminfo entry that specifies 256 colors is not going to change the capabilities of your terminal if it doesn't have them in the first place: it's the same as changing the label on a B&W TV and claim that it is a Color TV.. you won't get more colors by changing the label, just angry customers because you lied to them. The TERM variable & the terminfo entry only advertise the capabilities of your terminal. They have no power to change them.

This usually means that 256-colors support was disabled when the folks who packaged your distribution compiled the program. You should check in your terminal's documentation that the version of your program does support 256 colors. If so, it is probably disabled: you will have to download the program's source code and compile the program yourself, making sure you specify something like '--enable-256colors' when you run the ./configure script.

Another possible explanation is that '256colors2.pl' only works for terminal programs that are compatible with xterm escape sequences. If you try to run it on the linux console for instance, all you get to see is a few colored squares on a grey background and a lot of garbage. Careful, this usually wreaks havoc with your display and you will have to blindly type 'reset' to clean up the mess.

An application running inside a terminal determines its capabilities via the terminfo entry pointed to by the TERM environment variable. These so-called 'capabilities' include the number of colors the
terminal is capable of displaying. Of course, it is the underlying terminal's job to set the TERM environment variable so that it points to an entry in the 'terminfo' database that accurately describes its capabilities.

To display the name of the terminfo entry:

% echo $TERM

You could also use 'infocmp $TERM' to display the contents of the terminfo entry and check the value in the 'colors' field directly.

Generally, terminals that feature different color capabilities depending on how they are started/configured appear to default to the least color-capable entry ('xterm' for xterm, 'rxvt' for rxvt..)

Some terminals, such as xterm or rxvt (and derivatives such as rxvt-unicode, aterm, wterm..) feature a command-line flag to let the user choose the terminfo entry at startup:

% xterm -tn xterm-256color
% rxvt --termName rxvt-256color

This allows you to override the default terminfo entry set by the terminal and choose one that effectively describes its capabilities.

For convenience's sake, commands such as the above can then be bound to a shell alias, a keyboard shortcut, or in a desktop context, to a clickable icon.

Terminals that have this capability usually define a corresponding X resource: in this instance, the alternative to command-line flags is to set the resource in an .Xresources or .Xdefaults file.

Other terminals such as xfce4-terminal or Putty (pterm) do not have a command-line flag but rather provide a configuration GUI that lets the user specify the terminal type, or the number of colors. In this instance, the solution is to configure them via the GUI, save the new configuration and restart the terminal.

There are also terminals such as gnome-terminal, ROXterm, lxterminal.. that appear to provide neither of these mechanisms (unless the equivalent functionality is accessible through the gconf-editor..?). Worse yet, they systematically reset the content of the TERM environment variable to 'xterm', which makes it impossible to set TERM to a different value and export it, for instance in a wrapper script. A possible solution to this problem is to export the TERM variable after the fact, once they are launched.

Note, that a solution that consists in exporting the TERM variable in shell configuration scripts such as .bashrc or .bash_profile is too general in scope and likely to cause trouble down the line, long after you have forgotten all about it - you may rarely drop to a linux VT, but when you do, you won't like it if applications think that they are running in an xterm..! It makes better sense to implement such customization were it belongs.

There could be a number of reasons, and I can think of a few things you can check right away from the Vim command-line just to make sure they are the way you think they are.

Such as the contents of the TERM variable:

:echo $TERM

You can also verify that Vim correctly picked up the number of colors from the terminfo entry:

:set t_Co?

This is where Vim keeps track of the number of available colors and the output should be 't_Co=256'.

Of course, if it says t_Co=8 or t_Co=16, you could always try to reset 't_Co' manually and invoke the color scheme a second time:

:set t_Co=256
:color jellybeans

If this brings up your color scheme, it means that for some reason Vim was unable to pick up the correct number of colors from the terminfo entry, but I have never seen this happen.. One possible workaround in this particular case might be to add the above command (possibly testing the content of $TERM) in your vimrc but I would really not advise doing so without trying to figure out what's going on: it shouldn't happen.

Naturally, there is always the possibility that this is caused by something unrelated. So, you should check general options that affect highlighting, such as 'compatible'.. see :h syntax.. etc.

But if after giving it a rest and double-checking everything, all appears to be configured correctly, and yet the 256 colors feature is not working, it's probably best to ask for assistance on the #vim freenode/IRC channel or on the vim_use mailing list.

These two programs are not terminal emulations sensu stricto but rather terminal multiplexers that run on top of a terminal. If you use any of them, some minor customization is necessary. In order to have Vim use 256 colors when running on top of either one of these two programs, it is also necessary to make sure that 256-color support is enabled at configure|compile time. In other words, it's not just the underlying terminal but also the multiplexer that needs to support 256-color. And it is also necessary that the TERM variable point to a terminfo entry that advertises 256 colors at execution time.

For GNU/screen, here are the two statements you need to add to your screenrc:

term "screen-256color"
attrcolor b ".I" # use bright colors for bold

In tmux, you would add the following:

set -g default-terminal "screen-256color"

And, you also need to start tmux with the '-2' command-line flag:

% tmux -2 ... [options]

Not a typo: as yet, tmux does no ship with its own separate terminfo entry and relies on GNU/screen's.

In a nutshell, the difference with the basic procedure seen earlier is that now that we are dealing with what amounts to an extra 'terminal layer' we need to repeat step#2 and step#3 just after launching the multiplexer: as soon as you are in screen or tmux you need to run 256colors2.pl a second time and issue 'tput colors' again to verify that TERM is pointing to the correct terminfo entry.

Here is a quick list of features supported by a few popular terminals.

Terminal

Support

Default

Terminfo

Notes

xterm

yes

yes

xterm-256color

xterm -tn xterm-256color to set $TERM

rxvt

yes

no

rxvt-256color

xterm -tn rxvt-256color to set $TERM

Eterm

yes

yes

rxvt-256color

easiest of all: works out of the box

rxvt-unicode

no

n/a

rxvt-unicode

88 colors - requires patch for 256 color

mrxvt

yes

yes

mrxvt-256color

aterm

no

n/a

rxvt

no Unicode support either..?

wterm

no

n/a

rxvt

no Unicode support either..?

gnome-terminal

yes

yes

gnome-256color

sets $TERM to xterm by default

terminator

yes

yes

xterm

put "export TERM=xterm-256color" in .bashrc

xfce4-terminal

yes

no

xterm-256color

Preferences→Advanced to set $TERM

ROXTerm

yes

no

xterm

needs wrapper

lxterminal

yes

no

xterm

needs wrapper

Konsole

yes

yes

konsole-256color

untested (no access to KDE)

putty/pterm

yes

yes

putty-256color

need to export $TERM

GNU/screen

yes

no

screen-256color

minimal screen customization

tmux

yes

?

screen-256color

to be tested..

Notes:

aterm & wterm: TERM defaults to rxvt when the program is launched. I didn't see any 256color entries in terminfo. Are these programs still being developed?

There a gnome-256color entry in /usr/share/terminfo/g/ .. but gnome-terminal comes up with TERM=xterm by default.

I saw a putty-256color in /lib/terminfo/p/ but even after specifying 256 colors in the putty configuration GUI, pterm still came up with TERM=xterm. But the running 256colors2.pl showed that the terminal supports 256 colors.

man 5 terminator-config reveals terminator's terminfo entry can be set to something other than 'xterm' via the 'emulation' option. No indication it support 256 colors.

Perhaps gconf2 lets you change the default TERM value for gnome-terminal and set it to gnome-256color?