Set the Linux Console Font and Keyboard with setupcon

You have just reinstalled a Linux box and the console font is an unreadable blur, or the keyboard types the wrong symbols. setupcon reads the system's font and keyboard configuration and applies it to a Linux virtual console. This guide walks through that, then tests one change before you commit to it everywhere.

• Time: about fifteen minutes.
• You need: the console-setup package and a local text console.
• Privileges: elevated access only when changing files under /etc or applying the system-wide configuration.
• Versions: 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 where they differ, trust the help output and behaviour of the installed command.
• Warning: 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

Confirm the command and its two normal configuration files exist. These checks are read-only and need no 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 falls back to /etc/default/console-setup and /etc/default/keyboard. That user-level lookup is an easy distraction: a change to /etc/default can appear to do nothing when a hidden file in your home directory is actually taking precedence.

$ 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 lives in /etc/default/console-setup, one shell-style assignment per line. A practical UTF-8 baseline:

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.
• CODESET, FONTFACE and FONTSIZE select the glyph set and size.
• An empty VIDEOMODE avoids asking fbset to change the video mode, usually the least surprising choice since framebuffer drivers often reject mode changes.

For keyboard layout, edit /etc/default/keyboard, not console-setup. 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 your distribution's keyboard configuration already supports. 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 stop the setup working at all. 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 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 stops the test 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

5. Apply the keyboard and font system-wide

Once the current-tty test looks right, apply the complete configuration:

$ sudo setupcon

This uses the selected keyboard and console-setup files across the configured active consoles. The manual says keyboard setup normally needs doing 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 simply changes which configuration files are sought. The matching filenames matter, and the argument is case-sensitive in the filesystem. Omit the variant to return to the default configuration:

$ sudo setupcon

Back up the variant files before replacing them, for the same reversibility reasons as step 3. Deleting a variant is unnecessary; leaving it available makes it easier to switch back later.

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, the safer choice if the graphical server currently controls the screen, though 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.