Binding Mouse Buttons to Keyboard Keys on Linux

I’ve recently acquired a mouse that has extra buttons on it (side forward/back buttons), which I used on Windows for certain games. I discovered that while the keys were fairly easy to configure on Windows, it was more difficult to do on Linux. After looking up several guides, including information on the Arch Wiki, I had to put together something a bit different, which seems to be more simple than other suggestions I found. As a result, I’ve bound my forward and back keys on my mouse to Page Up and Page Down.I used for reference several different blogs found here, here and here, along with the information on the Arch Wiki.The resulting method utilizes the xbindkeys and xte commands, the latter being part of the xautomation package. Furthermore, the keys were determined with the xev command, which is is in the xorg-xev package. In order to acheive the desired results, be sure that these packages are installed, or that the commands are available (use which <command> to check if it is already present). As I use Arch Linux, none of these tools came pre-installed, and I had to install them manually. Note also, depending on the Linux distribution, the package required may be under a different name.

One advantage I had with the method I use over ones I’ve encountered is that the keys are already recognized by the system, but simply do not perform any actions. To check this, run the following command:

xev | grep -A 2 Button

With this, a window should appear on screen. Typically the xev command displays information about key presses, mouse button presses, and mouse movement. By utilizing grep, only information about mouse button presses is displayed. It should be noted that for some mouse buttons, the cursor must be over the window for them to be recognized. Upon pressing the buttons in question, output similar to the following should be displayed:

ButtonPress event, serial 33, synthetic NO, window 0x2400001,
root 0xd9, subw 0x2400002, time 39336395, (45,58), root:(74,142),
state 0x10, button 8, same_screen YES

ButtonRelease event, serial 33, synthetic NO, window 0x2400001,
root 0xd9, subw 0x2400002, time 39336530, (45,58), root:(74,142),
state 0x10, button 8, same_screen YES

As highlighted, the button number (in my case button 8 for the Forward button) indicates the identifier for the key relevant to this method for mapping it. Generally, buttons 1, 2 and 3 are reserved for left click, mouse wheel click, and right click respectively. If the mouse being tested has extra buttons, and these do not appear in the xev output, alternative methods must be used, which are not covered in this post. It is recommended to visit the related posts previously mentioned for such circumstances.

With the button number identified, mapping it to key presses is fairly simple with the xbindkeys command. Firstly, create a configuration file for it in the home directory, with the name .xbindkeysrc. This can be created manually, or using the tool itself (run: xbindkeys –defaults > $HOME/.xbindkeysrc) which will include some presets. I personally found nothing but frustration with these.

Next, the keys to which the buttons are to be mapped are to be identified. This can be accomplished by running the following command:

xbindkeys -k

With this running, press the key (or key combination) desired, and information about this will be displayed. In my case, the output resembled:

“(Scheme function)”
m:0x10 + c:117
Mod2 + Next

The name for the Page Down key press is Next (the Mod2 modifier is for the Number Lock, which is generally ignored by default). With the keys identified, the .xbindkeysrc file can be modified as desired:

#Pagedown press
“xte ‘keydown Next'”

#Pagedown release
“xte ‘keyup Next'”
b:8 + Release

These map the button press and release to use the xte command simulate key presses. It should be noted that, in my case, I desired having these buttons simulate both the press and release, so that the keys may be held. If only a simple combined press and release is desired, a single entry may be used:

“xte ‘key Next'”

With these configured, the kbindkeys process needs to be restarted:

killall xbindkeys #may fail if it was not already running


After this, a simple test with the mouse buttons will indicate if it is working. It should be noted that once re-mapped, the xev command will no longer recognize the button presses as such. In order for this configuration to be active upon boot/login, the xbindkeys command may be added as an auto-start application, or added to .bash_profile.


11 thoughts on “Binding Mouse Buttons to Keyboard Keys on Linux

  1. After spending an afternoon struggling with xorg.conf in ubuntu (only to learn that its use is discouraged), and then with xbindkeys, which didn’t really worked. I feel nothing but grateful for your post. Thank you!

    Alex 2017-06-06


  2. I have tried many methods,but none really works untill here,I nearly want to give up , thanks for your sharing!


  3. I think that the title is misleading as “binding mouse buttons to keyboard keys” would suggest that the mouse button would get sent after keyboard press, which is not the case here.
    I think it should be “binding keyboard actions under mouse”


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s