Set the Linux Console Font and Keyboard with setupcon

You will configure a Linux virtual console to use the font and keyboard settings in the system configuration, then test one change without touching every terminal. Allow about fifteen minutes. You need the console-setup package, a local text console, and elevated access only when changing files under /etc or applying the system-wide configuration.

This guide follows the installed console-setup package, version 1.226ubuntu1.1 on this machine. The command's manual page is older than the package, so the help output and behaviour of the installed command take precedence where they differ. A graphical terminal is not the Linux console: do not use --force from an X session unless you accept the possibility of needing a hard reboot.

1. Check the package and the files it will read

First confirm that the command and its two normal configuration files exist. These checks are read-only and do not need sudo:

$ command -v setupcon
/usr/bin/setupcon
$ dpkg-query -W -f='${Package} ${Version}\n' console-setup
console-setup 1.226ubuntu1.1
$ ls -l /etc/default/console-setup /etc/default/keyboard

With no variant, setupcon looks first for per-user files named ~/.console-setup and ~/.keyboard. If they do not exist, it uses /etc/default/console-setup and /etc/default/keyboard. That user-level lookup is an easy distraction: a change to /etc/default appears to do nothing if a hidden file in your home directory is taking precedence.

Checkpoint: inspect those possible overrides before editing the system files:

$ ls -l ~/.console-setup ~/.keyboard 2>/dev/null || true
$ sed -n '1,120p' /etc/default/console-setup
$ sed -n '1,120p' /etc/default/keyboard

2. Choose a small, valid console configuration

The console font configuration is in /etc/default/console-setup. It uses one shell-style assignment per line. A practical UTF-8 baseline is:

ACTIVE_CONSOLES="/dev/tty[1-6]"
CHARMAP="UTF-8"
CODESET="Uni2"
FONTFACE="Fixed"
FONTSIZE="8x16"
VIDEOMODE=

ACTIVE_CONSOLES selects virtual terminals; the wildcard shown covers tty1 through tty6. CHARMAP describes the encoding, while CODESET, FONTFACE and FONTSIZE select the glyph set and size. An empty VIDEOMODE avoids asking fbset to change the video mode. That is usually the least surprising choice because framebuffer drivers often reject mode changes.

For keyboard layout, edit /etc/default/keyboard, not console-setup. For example, a US layout is commonly represented as:

XKBMODEL="pc105"
XKBLAYOUT="us"
XKBVARIANT=""
XKBOPTIONS=""
BACKSPACE="guess"

Do not copy the example blindly if you need another layout. Use the layout name already supported by your distribution's keyboard configuration. The console-setup manual explicitly recommends keeping keyboard settings in the keyboard file.

3. Back up before editing

Changing the keyboard or font can make a console awkward to use, and a malformed file can prevent the intended setup. Make recoverable copies before editing. This is a state-changing step and needs elevated privileges:

$ sudo cp --preserve=all /etc/default/console-setup /etc/default/console-setup.bak
$ sudo cp --preserve=all /etc/default/keyboard /etc/default/keyboard.bak
$ sudoedit /etc/default/console-setup
$ sudoedit /etc/default/keyboard

Keep the backup names outside the normal names that setupcon searches. To undo the edit, restore the relevant backup and run the same setup command again:

$ sudo cp --preserve=all /etc/default/console-setup.bak /etc/default/console-setup
$ sudo cp --preserve=all /etc/default/keyboard.bak /etc/default/keyboard

4. Test only the current virtual terminal

Switch to a text console first, usually with Ctrl+Alt+F3. Then apply the font to that terminal only. The command changes the active console state, so save any work in that terminal first:

$ sudo setupcon --current-tty --font-only

--font-only leaves the keyboard and terminal settings alone. --current-tty prevents the test from applying the font to every configured virtual terminal. You should see the new glyph shape or size immediately; a normal successful run need not print a success message. If it fails, repeat with diagnostics:

$ sudo setupcon --current-tty --font-only --verbose

Checkpoint: confirm that the current console is readable and that the keyboard still produces the expected characters. If the font is wrong, restore the backup from step 3 and rerun the command, or return to the previous console before continuing.

5. Apply the keyboard and font system-wide

Once the current-tty test is acceptable, apply the complete configuration:

$ sudo setupcon

This uses the selected keyboard and console-setup files and targets the configured active consoles. On Linux, the manual says keyboard setup normally needs to be done only once, while font setup should be repeated when a new console driver is activated, such as when a framebuffer becomes active. That is why a later setupcon --font-only can be useful after a display-mode change.

If you only want to change the keyboard, use:

$ sudo setupcon --keyboard-only

For a font-only refresh across the configured consoles, use:

$ sudo setupcon --font-only

These commands affect console state, not the graphical desktop's input settings. If the result is not what you expect, check for a user-level override and run the verbose form before changing more variables.

6. Keep named variants for occasional layouts

A variant lets you keep alternatives without repeatedly rewriting the default files. For a variant named greek, create /etc/default/console-setup.greek and /etc/default/keyboard.greek with the appropriate values, then select both with one argument:

$ sudo setupcon greek

The variant files are not merged with the default pair: the variant name changes which configuration files are sought. The matching filenames matter, and the argument is case-sensitive in the filesystem. To return to the default configuration, omit the variant:

$ sudo setupcon

For a reversible experiment, back up the variant files before replacing them. Deleting a variant is unnecessary; leaving it available makes it easier to switch back when the alternate layout is useful.

7. Use boot-time caching only when you need it

--save copies required files into /etc/console-setup/ so setup can run early in boot before /usr is mounted. It changes cached system files and is not needed for an ordinary interactive test. If you deliberately use early boot console setup, rerun it with --save after each configuration change:

$ sudo setupcon --save

--save-only performs the copy without immediately setting up the keyboard or font. That is the safer choice if the graphical server currently controls the screen, but it still changes files under /etc/console-setup. Treat cached data as part of the configuration when recovering: restore the configuration files, then run sudo setupcon --save again so the cache matches them.