How To Bind Mouse Buttons To Keyboard Keys Or Commands (Linux Using X11)

If you have a mouse with extra buttons, you can bind those buttons to perform a key combination, run a program, command or script. This will only work if you use X11 (it does not work on Wayland) because the tools we'll use for this only support X11.

To bind the mouse buttons to key combinations we'll use the following tools:

  • xbindkeys: a program that grab keys and mouse button events in X and starts associated shell command
  • xev: a tool that prints contents of X events
  • xdotool: command-line X11 automation tool that lets you programmatically (or manually) simulate keyboard input and mouse activity (and more)

In case you don't need to bind mouse buttons to keyboard keys, and all you want to bind to the mouse buttons are programs, commands or scripts, you can skip the installation of xdotool.

1. Install xbindkeys, xev and xdotool.

  • Debian, Ubuntu, Linux Mint, Pop!_OS, Elementary OS and other Debian or Ubuntu based Linux distributions:
sudo apt install xbindkeys x11-utils xdotool

  • Fedora:
sudo dnf install xbindkeys xorg-x11-utils xdotool

  • openSUSE:
sudo zypper install xbindkeys xev xdotool

  • Arch Linux or Manjaro:
sudo pacman -S xbindkeys xorg-xev xdotool

On other Linux distributions you'll have to search in the repositories for xdotool, xev and xbindkeys and install them.

2. Grab the mouse button codes.

To get the mouse button code(s), run this command:

xev | grep button

Next, focus the small window that pops up and watch the terminal output. Now press the mouse button for which you want to grab the code. After pressing the button you should see its code in the terminal where you ran xev, e.g.:

$ xev | grep button

state 0x10, button 8, same_screen YES

In this example, the button code we'll need later is 8.

3. Grab the keystrokes that we'll later send using a mouse button (skip if you want to bind a command / script / program to a mouse button)

Open a terminal and run this command (via AskUbuntu):

xev | sed -ne '/^KeyPress/,/^$/p'

Once again, a small window will pop up that you need to focus. Next, press the keys on your keyboard that you want to remap to your mouse, each at a time, and watch the xev command output in the terminal.

For example if you want to bind Ctrl + Alt + Up to a mouse button, press Ctrl, then Alt and finally Up. In my case, this is the output of xev for these 3 key presses (the first one is for Control_L or left Control key, the second for Alt_L or left Alt, and the third is for Up:

KeyPress event, serial 33, synthetic NO, window 0x2200001,
    root 0x1eb, subw 0x0, time 6741696, (46,-37), root:(728,598),
    state 0x10, keycode 37 (keysym 0xffe3, Control_L), same_screen YES,
    XLookupString gives 0 bytes: 
    XmbLookupString gives 0 bytes: 
    XFilterEvent returns: False

KeyPress event, serial 36, synthetic NO, window 0x2200001,
    root 0x1eb, subw 0x0, time 6743289, (46,-37), root:(728,598),
    state 0x10, keycode 64 (keysym 0xffe9, Alt_L), same_screen YES,
    XLookupString gives 0 bytes: 
    XmbLookupString gives 0 bytes: 
    XFilterEvent returns: False

KeyPress event, serial 36, synthetic NO, window 0x2200001,
    root 0x1eb, subw 0x0, time 6744780, (46,-37), root:(728,598),
    state 0x10, keycode 111 (keysym 0xff52, Up), same_screen YES,
    XLookupString gives 0 bytes: 
    XmbLookupString gives 0 bytes: 
    XFilterEvent returns: False

Note down the keycode, keysim or name of the key. You can use any of the 3, e.g. for the first key above you can use either 37, 0xffe3, or Control_L. In this article I'll use the key name (e.g. Control_L for left control key) since they are easier to read.

It's worth noting that xbindkeys can be used grab the keycodes too (xbindkeys -k), but it reads all active keys so it can be confusing in some cases, e.g. if you have Caps_Lock or Num_Lock on, etc., so I personally prefer to use xev for this task.

Neither xed nor xbindkeys -k will show the keycodes / keyboard symbols for multimedia keys. In case you want to remap multimedia keys to mouse buttons, you can get a list of such keyboard symbols by visiting this link.

Mouse-related article: How To Disable Mouse Acceleration In Ubuntu 18.04 Or 19.10 (Gnome).

4. Create the xbindkeys configuration (in ~/.xbindkeysrc).

You may either create an empty ~/.xbindkeysrc file, or generate a sample configuration file using this command:

xbindkeys -d > ~/.xbindkeysrc

Next, open ~/.xbindkeysrc with your favorite text editor. Note that .xbindkeysrc is a hidden file in your home directory so you'll need to press Ctrl + h (to show hidden files and folders) to see it in your file manager.

To bind a mouse button to a key combination, paste the following at the end of the ~/.xbindkeysrc file (it may already contain some key binds, it may contain the sample configuration or it can be empty - it doesn't matter):

"xdotool key 'KEY-COMBINATION'"
       b:MOUSE-BUTTON-CODE

Where:

  • KEY-COMBINATION are the keystrokes you got under step 3 (separate the keys with a + sign)
  • MOUSE-BUTTON-CODE is the mouse button code that you got under step 2

Example:

"xdotool key 'Control_L+Alt_L+Down'"
       b:8

This remaps the mouse button 8 (which for my mouse is the button that can be used as a back button in a web browser for example) to Control_L+Alt_L+Down which in GNOME Shell is used to switch to workspace down.

To also remap the mouse forward button (mouse button 9 in my case) to Control_L+Alt_L+Up (switch to workspace up in GNOME Shell), I'd have to add this to the ~/.xbindkeysrc file:

"xdotool key 'Control_L+Alt_L+Up'"
       b:9

Another example. To bind the keyboard media keys for raising and lowering the volume to mouse buttons 8 and 9:

"xdotool key 'XF86AudioRaiseVolume'"
       b:9

"xdotool key 'XF86AudioLowerVolume'"
       b:8

In the same way, add as many key binds as you wish, but make sure you're not using some already existing key combinations.

To bind a command, script or program to a mouse button, use this in the ~/.xbindkeysrc file:

"COMMAND"
       b:MOUSE-BUTTON-CODE

Here:

  • COMMAND is a command, script or program
  • MOUSE-BUTTON-CODE is the mouse button code that you got under step 2

You may also like: Run Or Raise Application Windows On Linux (X11) Using A Single Keyboard Shortcut With jumpapp.

Example for running a program using a mouse button:

"firefox"
       b:8

This starts Firefox when pressing mouse button 9 (which for my mouse is the button that can be used as a back button in a web browser for example).

5. Start xbindkeys.

Now you can start xbindkeys using a terminal and typing:

xbindkeys

In case xbindkeys was running, you can get it to use the new configuration by issuing:

xbindkeys --poll-rc

This command failed in a few cases for me when I changed the xbindkeys configuration, I'm not sure why. In such a case you can restart it by killing the xbindkeys process and running it again:

killall xbindkeys
xbindkeys

On Ubuntu, xbindkeys is automatically started on system startup if it finds a non-empty (it needs to have lines that are not commented out) ~/.xbindkeysrc configuration file. If the tool doesn't automatically start for the Linux distribution you're using, add xbindkeys to your startup programs.