Set and Restore Linux Virtual Terminal Colours with setvtrgb

Someone tried a "nicer" console colour scheme last week and now half the text is unreadable over a virtual terminal. setvtrgb is what set that palette, and it is what puts it back. You will finish with a saved colour map, a controlled way to apply a new one to Linux virtual terminals, and a reliable restore command. The examples use setvtrgb from kbd 2.6.4, installed here as package version 2.6.4-2ubuntu2. Allow about ten minutes for a test and a further few minutes if you are choosing colours by hand.

• You need: a Linux virtual terminal, the kbd package, permission to read the kernel's VT parameters, and root access for the colour-map change on most systems.
• Scope: this command changes the console colour map in all virtual terminals. It does not configure a graphical terminal emulator such as GNOME Terminal or Konsole.

Checkpoint: keep a root shell or a second login available before applying a new map. An unreadable colour scheme can make the current console awkward to use, even though the change is reversible.

1. Check the installed command

Start with read-only checks. They need no elevated privileges:

$ command -v setvtrgb
/usr/sbin/setvtrgb
$ setvtrgb --version
setvtrgb from kbd 2.6.4
$ setvtrgb --help
Usage: setvtrgb [option...] [vga|FILE|-]

The installed help is more current than the local setvtrgb(1) page in one useful respect. The page documents the original decimal format and the vga restore argument. This installed build also accepts hexadecimal files, standard input, and -C or --console to select a console device. Check the help on another kbd version rather than assuming those details are portable.

2. Save the current map as your undo point

The kernel exposes the built-in VT red, green and blue values as three files. Read them into one decimal map file in your home directory:

$ umask 077
$ cat /sys/module/vt/parameters/default_{red,grn,blu} > "$HOME/vt-colours.backup"
$ wc -l "$HOME/vt-colours.backup"
3 /home/you/vt-colours.backup

Replace /home/you in the displayed result with your actual home directory. The file should have three lines, each with sixteen comma-separated decimal values: the red, green and blue components for colour slots 0 through 15. This command reads defaults exposed by the kernel, the documented way to seed a valid decimal file, but it may not describe a colour map that another program has already applied.

If a parameter file is missing, stop and inspect the host rather than inventing a map. The machine may not have the virtual-terminal kernel support this command needs.

3. Understand the sixteen colour slots

Each line has one component for each slot. Slots 0 to 7 are the normal colours, and slots 8 to 15 are their bright counterparts:

Values are decimal numbers from 0 to 255. A pure red slot, for example, has red 255, green 0 and blue 0. Do not edit one line in isolation and expect a complete colour: all three lines together define the map.

4. Create a small test map

Make a copy of the backup before editing. This example changes the red component of slot 1, the normal red used by many shells and programs, to 180, leaving every other component unchanged:

$ cp --preserve=mode,ownership,timestamps "$HOME/vt-colours.backup" "$HOME/vt-colours.test"
$ awk -F, 'BEGIN { OFS="," } NR == 1 { $2 = 180 } { print }' "$HOME/vt-colours.backup" > "$HOME/vt-colours.test"
$ sed -n '1,3p' "$HOME/vt-colours.test"
# your three comma-separated lines should be visible here

The first line contains red components, so $2 is slot 1's red value. A safer manual approach is to copy the three lines into an editor and change only the value you intend to change. Keep exactly three lines and sixteen values per line. The installed 2.6.4 command can also read a hexadecimal format of sixteen #RRGGBB lines, but the decimal format is easier to seed and compare against the kernel files.

5. Apply the map deliberately

Warning: this is the state-changing step. It affects all virtual terminals and normally requires elevated privileges. It does not permanently alter the kernel defaults or a boot configuration, but running it changes the active map immediately.

$ sudo setvtrgb "$HOME/vt-colours.test"
$ printf 'setvtrgb exit status: %s\n' "$?"
setvtrgb exit status: 0

A zero exit status means the command accepted the file and completed. The shell prints no success message of its own. Switch to another VT with Ctrl-Alt-F3, or open a new console session, to see that the active map is shared across virtual terminals. The function-key combination varies by desktop and hardware, so do not treat a failed switch as evidence the colour change failed.

6. Restore the previous map

Restore the saved file if the colours are hard to read or the test is finished:

$ sudo setvtrgb "$HOME/vt-colours.backup"
$ printf 'restore exit status: %s\n' "$?"
restore exit status: 0

The built-in kernel palette is a separate restore option:

$ sudo setvtrgb vga

Use vga when you specifically want the kernel's built-in settings; use the backup file when you want the state captured before this test. Neither command writes a persistent configuration file, so a reboot or a console-management service may establish a different map later.

7. Diagnose rejected files

Validate the file before applying it:

$ awk -F, 'NF != 16 { print "line", NR, "has", NF, "values"; bad=1 } END { exit bad }' "$HOME/vt-colours.test"
$ awk -F, '{ for (i = 1; i <= NF; i++) if ($i !~ /^[0-9]+$/ || $i < 0 || $i > 255) { print "bad value on line", NR; bad=1 } } END { exit bad }' "$HOME/vt-colours.test"

• These checks cover the decimal shape, not every parser detail. A non-zero status means do not run sudo setvtrgb yet.
• Check for blank lines, spaces or hexadecimal values in what should be a decimal file, and check the file is readable.
• An unavailable console error can mean you are in a container, over SSH without a local VT, or inside a graphical terminal. There is then no local virtual-terminal colour map for this command to change.

Done means

• You confirmed the installed kbd and setvtrgb versions.
• You saved a three-line backup before changing anything.
• Your custom file has three lines and sixteen decimal values per line.
• You applied the map with elevated privileges only after checking it.
• You can restore the backup or select the built-in vga palette.
• You understand the active change affects virtual terminals, not graphical terminal windows.