Vim Tips Wiki

Proposed tip Please edit this page to improve it, or add your comments below (do not use the discussion page).

Please use new tips to discuss whether this page should be a permanent tip, or whether it should be merged to an existing tip.
created May 4, 2012 · complexity basic · author Cjns1989 · version 7.0

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.

General approach[]

The procedure is pretty straightforward:

  1. 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.
  2. Check that your terminal is capable of displaying 256 colors: Fire up a terminal session and run 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.
  3. 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.
  4. 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.
  5. 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.


Problems that you might run into and how you may be able to fix them: shows only a few colors[]

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

Terminal displays 256 colors but tput only reports 8 colors[]

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

Overriding the terminal's default terminfo[]

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.

Vim still does not display the color scheme correctly[]

Even after you followed the above procedure to the letter..?

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.

GNU/screen and Tmux[]

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 a second time and issue 'tput colors' again to verify that TERM is pointing to the correct terminfo entry.

Terminal recap[]

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 no no konsole-256color support available but buggy, see this bug report
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..
pantheon-terminal yes no export TERM=screen-256color in .bashrc /


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


Some useful stuff that does not fit in anywhere, mostly relative to downloads.

  • There are many well-written color schemes with screenshots at Search with keyword '256' for a complete list.
  • is available from the vttests directory in the xterm source tree:
  • In debian (and probably ubuntu) most terminfo entries are in package 'ncurses-term' (not installed by default)
  • man infocmp, terminfo, etc. for the technically-minded


to be completed ...


Related tips:

Thanks for the new tip. The above list shows tips that may be useful, or which may need fixing or merging. JohnBeckett 08:09, May 4, 2012 (UTC)