When set to "dark", Vim will try to use colors that look good on a dark background. When set to "light", Vim will try to use colors that look good on a light background. Any other value is illegal. Vim tries to set the default value according to the terminal used. This will not always be correct. Setting this option does not change the background color, it tells Vim what the background color looks like. For changing the background color, see :hi-normal.

When 'background' is set Vim will adjust the default color groups for the new value. But the colors used for syntax highlighting will not change. When a color scheme is loaded (the "g:colors_name" variable is set) setting 'background' will cause the color scheme to be reloaded. If the color scheme adjusts to the value of 'background' this will work. However, if the color scheme sets 'background' itself the effect may be undone. First delete the "g:colors_name" variable when needed.

When setting 'background' to the default value with:

:set background&

Vim will guess the value. In the GUI this should work correctly, in other cases Vim might not be able to guess the right value. If the GUI supports a dark theme, you can use the "d" flag in 'guioptions', see 'go-d'.

When the t_RB option is set, Vim will use it to request the background color from the terminal. If the returned RGB value is dark/light and 'background' is not dark/light, 'background' will be set and the screen is redrawn. This may have side effects, make t_BG empty in your .vimrc if you suspect this problem. The response to t_RB can be found in v:termrbgresp.

When starting the GUI, the default value for 'background' will be "light". When the value is not set in the .gvimrc, and Vim detects that the background is actually quite dark, 'background' is set to "dark". But this happens only AFTER the .gvimrc file has been read (because the window needs to be opened to find the actual background color). To get around this, force the GUI window to be opened by putting a ":gui" command in the .gvimrc file, before where the value of 'background' is used (e.g., before ":syntax on").

For MS-Windows the default is "dark". For other systems "dark" is used when 'term' is "linux", "screen.linux", "cygwin" or "putty", or $COLORFGBG suggests a dark background. Otherwise the default is "light".

The :terminal command and the term_start() function use the 'background' value to decide whether the terminal window will start with a white or black background.

Normally this option would be set in the .vimrc file. Possibly depending on the terminal name. Example:

:if &term == "pcterm"
:  set background=dark
:endif

When this option is set, the default settings for the highlight groups will change. To use other settings, place ":highlight" commands AFTER the setting of the 'background' option. This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file to select the colors for syntax highlighting. After changing this option, you must load syntax.vim again to see the result. This can be done with ":syntax on".

(default "dark" or "light", see below)