sxhkd - ArchWiki

Jump to content
From ArchWiki

Related articles

- Xbindkeys
- Xmodmap

sxhkd is a simple X hotkey daemon, by the developer of bspwm, that reacts to input events by executing commands.

## Installation

Install sxhkd or sxhkd-gitAUR.

## Configuration

sxhkd defaults to `$XDG_CONFIG_HOME/sxhkd/sxhkdrc` for its configuration file. An alternate configuration file can be specified with the `-c` option.

Each line of the configuration file is interpreted as so:

- If it starts with `#`, it is ignored.
- If it starts with one or more white space commands, it is read as a command.
- Otherwise, it is parsed as a hotkey: each key name is separated by spaces and/or `+` characters.

General syntax:

    [MODIFIER + ]*[@]KEYSYM
        COMMAND

Where `MODIFIER` is one of the following names: `super`, `hyper`, `meta`, `alt`, `control`, `ctrl`, `shift`, `mode_switch`, `lock`, `mod1`, `mod2`, `mod3`, `mod4`, `mod5`. If `@` is added at the beginning of the keysym, the command will be run on key release events, otherwise on key press events. The `KEYSYM` names are those your will get from `xev`.

Mouse hotkeys can be defined by using one of the following special keysym names: `button1`, `button2`, `button3`, ..., `button24`. The hotkey can contain a sequence of the form `STRING_1`, ...,`STRING_N`}, in which case, the command must also contain a sequence with N elements: the pairing of the two sequences generates N hotkeys. If the command includes curly braces (`{`, `}`) eg. `awk '{print $1}'`, escape them with backslash `\` eg. `awk '\{print $1\}'`. In addition, the sequences can contain ranges of the form `A-Z` where A and Z are alphanumeric characters.

What is actually executed is `SHELL -c COMMAND`, which means you can use environment variables in `COMMAND`. `SHELL` will be the content of the first defined environment variable in the following list: `SXHKD_SHELL`, `SHELL`. If sxhkd receives a `SIGUSR1` signal, it will reload its configuration file.

### Example

    $XDG_CONFIG_HOME/sxhkd/sxhkdrc

    # On mouse button 1 press Alt_R+F1
    button1
        xte "keydown Alt_R" "keydown F1" "keyup Alt_R" "keyup F1"

    # On mouse button 2 pause 3 seconds then press Alt_R+F2
    button2
        xte "sleep 3" "keydown Alt_R" "keydown F2" "keyup Alt_R" "keyup F2"

#### Bind a command to a single press of a key

Some users may wish to bind a command to a single keypress, in the way that the `Super` key opens the Start menu on Windows. In sxhkd, this is accomplished by binding to a chord chain composed of the key press and key release event of a single keysym, as in the following:

    $XDG_CONFIG_HOME/sxhkd/sxhkdrc

    # Program launcher
    Super_L; @Super_L
        rofi -show drun

This complicated pattern is necessary because without the explicit chord chain (i.e. a single `@Super_L`, sxhkd would trigger the binding on any release of the key—even when the key is used in another chord. Furthermore, keysyms must be used instead of modifiers (`Super_L` as opposed to `super`) because sxhkd does not support the use of the `@` symbol (denoting key release) for modifiers.

## Usage

After configuring it, you may wish to setup sxhkd to autostart; see the corresponding article for your desktop environment or window manager for details.

If your desktop environment supports the Desktop Application Autostart Specification you can start sxhkd by creating an `sxhkd.desktop` file in the appropiate directory:

    ~/.config/autostart/sxhkd.desktop

    [Desktop Entry]
    Name=sxhkd
    Comment=Simple X hotkey daemon
    Exec=/usr/bin/sxhkd
    Terminal=false
    Type=Application

## See also

- Official website - includes configuration options, example bindings, and source code.
- Arch Linux forum thread

Categories:

- Keyboard configuration
- X server