LOCALECTL(1)

NAME
localectl - control the system locale and keyboard layout

SYNOPSIS
localectl [--no-convert] COMMAND [ARGUMENT...]

DESCRIPTION
localectl is a Bash client used to query and change the system locale and keyboard layout configuration.

Unlike a typical D-Bus client, localectl writes directly to /etc/locale.conf and /etc/vconsole.conf (and, for X11 keyboard settings, /etc/X11/xorg.conf.d/00-keyboard.conf). The localed daemon watches these files with inotify(7) and automatically updates its org.freedesktop.locale1 D-Bus properties and emits PropertiesChanged signals whenever they are modified, whether by localectl or any other tool. This means localectl itself never talks to D-Bus or PolKit; it relies on ordinary file permissions, and most subcommands require root.

COMMANDS

status
    Show the current locale and keyboard configuration in human-readable form. This is the default command when none is given.

list-keymaps [FILTER]
    List all console keymaps installed under /usr/share/kbd/keymaps/. Keymap names are derived by stripping the directory path and .map.gz (or .map) extension from each file found. The optional FILTER argument is passed to grep(1) as a case-insensitive pattern. Does not require root.

list-locales [FILTER]
    List all locales available to the C library via locale -a. The optional FILTER argument is passed to grep(1) as a case-insensitive pattern, so localectl list-locales en_US narrows the output to en_US locales only. Does not require root.

set-locale KEY=value [KEY=value ...]
    Set one or more locale variables. KEY must be one of LANG, LANGUAGE, LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, LC_PAPER, LC_NAME, LC_ADDRESS, LC_TELEPHONE, LC_MEASUREMENT, or LC_IDENTIFICATION. Each assignment is written to /etc/locale.conf. Passing an empty value (e.g. LC_TIME=) removes that key from the file.

set-keymap KEYMAP [KEYMAP_TOGGLE]
    Set the virtual console keymap (and optionally the toggle keymap). Written to /etc/vconsole.conf as KEYMAP and KEYMAP_TOGGLE.

set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]]
    Set the X11 keyboard layout. LAYOUT is required; all other arguments are optional. Any argument not supplied is read from the current X11_KEYBOARD_FILE and preserved unchanged, so you can update a single field without having to repeat all the others. Pass an explicit empty string ("") to clear a field. Written to /etc/X11/xorg.conf.d/00-keyboard.conf.

OPTIONS

--no-convert
    When used with set-keymap or set-x11-keymap, suppress the automatic conversion between the console keymap and the X11 keyboard layout. Without this flag, set-keymap also updates the X11 keyboard layout using the built-in conversion table, and set-x11-keymap also updates the console keymap. The conversion is best-effort; if no table entry exists for the given keymap or layout, the other side is left unchanged rather than guessing.

-h, --help
    Show a short usage summary and exit.

EXAMPLES

Show the current status:

        localectl status

List all available locales:

        localectl list-locales

List only en_US locales:

        localectl list-locales en_US

Set the system locale:

        localectl set-locale LANG=en_US.UTF-8

Set multiple locale variables at once:

        localectl set-locale LANG=en_US.UTF-8 LC_TIME=en_GB.UTF-8

Set the console keymap:

        localectl set-keymap us

Set the X11 keyboard layout with a variant:

        localectl set-x11-keymap de pc105 nodeadkeys

Set the X11 layout, model, variant, and compose key option:

        localectl set-x11-keymap us pc105 "" compose:ralt

list-x11-keymap-models [FILTER]
    List available X11 keyboard models from /usr/share/X11/xkb/rules/base.lst. The optional FILTER is matched case-insensitively against the model code and description.

list-x11-keymap-layouts [FILTER]
    List available X11 keyboard layouts.

list-x11-keymap-variants [LAYOUT] [FILTER]
    List available X11 keyboard variants. When LAYOUT is given, only variants that apply to that layout are printed (matching the “LAYOUT:” prefix in base.lst). FILTER is applied on top of the layout restriction.

list-x11-keymap-options [FILTER]
    List available X11 keyboard options (e.g. compose key, Ctrl placement).

EXIT STATUS
Returns 0 on success and 1 on error (for example, an unknown locale variable, an invalid value, a missing argument, or insufficient permissions).

AUTHORIZATION
All subcommands other than status require root. There is no PolKit prompt or D-Bus round trip in localectl itself; the daemon's PolKit policy governs only direct D-Bus callers such as gnome-control-center(1).

FILES

/etc/locale.conf
    System locale settings. Rewritten atomically (temporary file plus rename) on every write. Created automatically on first root invocation if missing.

/etc/rc.d/rc.keymap
    Slackware console keyboard script. Regenerated atomically on every set-keymap invocation. The directory is created automatically if missing.

/etc/rc.d/rc.keymap.toggle
    Sidecar file for the toggle keymap. Created when a toggle keymap is set; removed when the toggle is cleared.

/etc/X11/xorg.conf.d/00-keyboard.conf
    Xorg InputClass keyboard configuration. Rewritten atomically on every write. The parent directory is created automatically if missing.

SEE ALSO
localed(8), locale.conf(5), vconsole.conf(5), inotify(7)

AUTHOR
Written by Nathaniel Russell.

Part of the localed project, a non-systemd implementation of the org.freedesktop.locale1 D-Bus interface for Slackware Linux.

LICENSE
This program is free software, distributed under the GNU General Public License, version 2 or later. See the source for copying conditions.