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:
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.
On other Linux distributions you'll have to search in the repositories for
2. Grab the mouse button codes.
To get the mouse button code(s), run this command:
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.:
In this example, the button code we'll need later is
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):
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
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
It's worth noting that xbindkeys can be used grab the keycodes too (
Neither
Mouse-related article: How To Disable Mouse Acceleration In Ubuntu 18.04 Or 19.10 (Gnome).
4. Create the xbindkeys configuration (in
You may either create an empty
Next, open
To bind a mouse button to a key combination, paste the following at the end of the
Where:
Example:
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
To also remap the mouse forward button (mouse button 9 in my case) to
Another example. To bind the keyboard media keys for raising and lowering the volume to mouse buttons 8 and 9:
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
Here:
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:
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:
In case xbindkeys was running, you can get it to use the new configuration by issuing:
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:
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)
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 xdotoolOn 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 buttonNext, 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 YESIn 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: FalseNote 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 > ~/.xbindkeysrcNext, 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-CODEWhere:
KEY-COMBINATIONare the keystrokes you got under step 3 (separate the keys with a+sign)MOUSE-BUTTON-CODEis the mouse button code that you got under step 2
Example:
"xdotool key 'Control_L+Alt_L+Down'"
b:8This 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:9Another 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:8In 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-CODEHere:
COMMANDis a command, script or programMOUSE-BUTTON-CODEis 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:8This 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:
xbindkeysIn case xbindkeys was running, you can get it to use the new configuration by issuing:
xbindkeys --poll-rcThis 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
xbindkeysOn 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.
