I struggled with this over the weekend, and need to remap my mouse buttons.

5 Answers 5


I have a Logitech mouse with 9 buttons, and pressing the "middle button" (#2) involves clicking the scroll wheel. I dislike this because I'm clumsy and typically end up scrolling the window I'm in when I try to click the wheel. So I wanted to automatically remap the top side button (#9 in this case) to the middle button (#2). I also wanted to map the bottom side button (#8) so that it executes a double-click of the left button (#1).

Though my aims were specific, the solutions below can be generalized to any situation in which you want to automatically remap mouse buttons at startup.

Mapping Mouse Buttons to Other Mouse Buttons

You will need xinput installed for this task. This can be done entirely in your .xsessionrc file. First, use xinput to discover the name that is assigned to your mouse, which is then correlated to an input device ID. Below is some sample output from my laptop:

⎡ Virtual core pointer                      id=2    [master pointer  (3)]
⎜   ↳ Virtual core XTEST pointer            id=4    [slave  pointer  (2)]
⎜   ↳ Logitech USB Laser Mouse              id=11   [slave  pointer  (2)]
⎣ Virtual core keyboard                     id=3    [master keyboard (2)]
    ↳ Virtual core XTEST keyboard           id=5    [slave  keyboard (3)]

My mouse calls itself Logitech USB Laser Mouse and is shown as id=11. Your mouse will have a different name; figuring that out is left as an exercise for the reader.

While you still know the ID of the device in this session, find out how many buttons the input handler thinks your mouse has, by using xinput list deviceID. This may be different from the number of buttons that is apparent on the device.

Logitech USB Laser Mouse                    id=11   [slave  pointer  (2)]
    Reporting 7 classes:
        Class originated from: 11. Type: XIButtonClass
        Buttons supported: 16
        Button labels: "Button Left" "Button Middle" "Button Right" "Button Wheel Up" "Button Wheel Down" "Button Horiz Wheel Left" "Button Horiz Wheel Right" "Button Side" "Button Extra" "Button Forward" "Button Back" "Button Task" "Button Unknown" "Button Unknown" "Button Unknown" "Button Unknown"

With my mouse, there are only 9 obvious physical buttons, but xinput reports 16.

Given the nature of USB, this ID can change every time you restart, so it's not enough to script something that's statically keyed to an ID you discover once. You'll have to dynamically parse this at startup and execute your re-map based on the current ID.

Now that you know its name, you can use xinput test deviceID to figure out which key to remap. Press the mouse buttons you want to map from and to, in order to get their indices. (For reference, 1, 2, and 3 "always" (i.e., usually) refer to the left, middle, and right buttons of a 3-button mouse. A common re-map reverses these to make the mouse left-handed.)

button press   2
button release 2
button press   9
button release 9

In this case I found that I want to map button #9 (side, top) to button #2 (middle).

Now that you know what your mouse is called, and which buttons you want to change, you can write an ~/.xsessionrc script that invokes xinput to execute the button re-mapping at startup. Below is my complete script.

# Map button 9 (top side button) to button 2 (middle button)
my_mouse_id=$(xinput | grep -m 1 "Logitech USB Laser Mouse" | sed 's/^.*id=\([0-9]*\)[ \t].*$/\1/')
echo $my_mouse_id > ~/temp/my_mouse_id
xinput set-button-map $my_mouse_id 1 2 3 4 5 6 7 8 2 10 11 12 13 14 15 16

The first line here sets a temporary session variable equal to the ID of the mouse as reported by xinput. This is done by greping for the known name of the mouse in the report from xinput, then using sed to extract the ID number from that id=xxx token in the report. This value is then used in an xinput set-button-map directive, which executes the re-mapping. In the example above, the only change is that button #9 is being re-mapped to mimic button #2. All others remain at their default setting.

Update: As @Lokasenna points out below, if your device reports itself as both a mouse and a keyboard, you may need to limit the result count of the grep using -m 1. This will not cause problems if the mouse doesn't report itself as both, so it's been included in the script.

Mapping Mouse Buttons to Arbitrary Functions

See also this answer.

You will need xinput, xbindkeys, and xautomation (including xte) installed for this task.

Use xinput list and xinput test to discover your mouse's device ID and the number of the button you want to assign. In my case, I wanted to map the bottom side button (#8) to a double-click of the left button (#1).

Create or edit ~/.xbindkeysrc. The format of this file is a series of paired lines. The first line is a command to be executed for an event; the second line is the event description. We will use the xte component of xautomation to send events directly to the input handler.

To create a double-click event when a button is released, I added the following:

"/usr/bin/xte 'mouseclick 1' 'mouseclick 1' &"
b:8 + Release

This configuration maps a sequence of two mouse clicks on button #1 to the release of button #8. (In theory I guess you could map any command to a mouse button, but this is the most common case. See this answer for other practical examples.)

Update for 16.04 Ubuntu

For users with multiple mice attached to your system, you need to also pass in the ID of the device. This may not apply to all users and was discovered on Ubuntu 16.04 with Unity.

xinput list

⎡ Virtual core pointer                      id=2    [master pointer  (3)]
⎜   ↳ Virtual core XTEST pointer                id=4    [slave  pointer  (2)]
⎜   ↳ Kensington      Kensington Expert Mouse   id=9    [slave  pointer  (2)]
⎜   ↳ SynPS/2 Synaptics TouchPad                id=13   [slave  pointer  (2)]
⎜   ↳ TPPS/2 IBM TrackPoint                     id=14   [slave  pointer  (2)]

Then modify the .xbindkeysrc file by referencing the id= value from the command output (id=9 in this example):

"/usr/bin/xte -i 9 'mouseclick 1' 'mouseclick 1' &"
b:8 + Release
  • 7
    Thanks for the information. Your awk looks like it would need changing based on the number of words in the device. I used sed 's/^.*id=\([0-9]*\)[ \t].*$/\1/'
    – jbo5112
    Commented Sep 23, 2016 at 0:09
  • According to xinput test thumb key triggers three different key press - how to bind them all together in .xbindkeysrc?
    – axltop
    Commented Feb 16, 2017 at 8:31
  • @jbo5112 I just started using multiple mice on my work laptop, and had good cause to revisit your comment. I've now replaced my old awk statement with your sed statement in my examples. Thanks for the improvement! Commented May 25, 2017 at 14:35
  • 3
    There is no need to use an id in set-button-map; e.g.: xinput set-button-map "Logitech Trackball" 1 3 3
    – jaustin
    Commented Jul 18, 2017 at 2:11
  • 1
    People asking if there is a better way than grepping device IDs: stackoverflow.com/questions/18755967/… There isen't! :-( Commented Jun 10, 2020 at 22:42

Short steps for this are:

There is a utility called xinput. xinput list or just xinput will show all the X input devices and theirs IDs. Here you find ID of the mouse which you want to remap.

I will use my ID as example, from my setup, which is 21, then xinput --get-button-map 21 will output

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

Now, if you want to, say, swap left and right buttons you simply run

xinput --set-button-map 21 3 2 1

Here we are, remapping is done.

For running it at startup just put this into a file:

echo "xinput --set-button-map 21 3 2 1" > leftmouseremap.sh

give it executable permission

chmod +x leftmouseremap.sh 

Finally, add this to Statrtup Application manually from GUI or , if you want it from CLI, put text below (change paths to yours) inti a file in your ~/.config/autostart, here is mine (less .config/autostart/leftmouseremap.sh.desktop):

[Desktop Entry]

Keep in mind, that with KDE the path would be like ~/.kde/Autosart, for others Desktop managers this might be sightly different. Alternatively, startup running can be done with general approach by using /etc/rc.local.

  • This solved my water spill issue. I have left/right click buttons below my laptop's touchpad. I spilled water and now both buttons send a middle-click signal to the OS (I discovered this using the 'keymon' app). I used your method to remap middle-click to left-click, so I can at the very least enjoy a left-click experience. I never use middle-click so this works perfectly for me :) Thanks for the simple instructions. My input device ID was 11, so I ran "xinput --set-button-map 11 1 1 3" Thanks!! Commented Sep 20, 2019 at 20:31
  • excellent; xinput --set-button-map 10 1 2 3 4 5 6 7 8 1 remapped forward-button of my anywhere mx to left click while I wait for a new main button micro-switch to arrive..
    – eMPee584
    Commented May 12, 2020 at 13:20
  • As mentioned at askubuntu.com/a/492745/52975 my ID numbers change on 20.04 unfortunately, I need their grep. Commented Jun 7, 2020 at 18:24

When using zerobandwidth's great answer, some devices, such as Logitech's MX Ergo, show up as both a pointer and a keyboard device:

⎡ Virtual core pointer                          id=2    [master pointer  (3)]
⎜   ↳ Virtual core XTEST pointer                id=4    [slave  pointer  (2)]
⎜   ↳ Logitech MX Ergo                          id=10   [slave  pointer  (2)]
⎜   ↳ SynPS/2 Synaptics TouchPad                id=14   [slave  pointer  (2)]
⎣ Virtual core keyboard                         id=3    [master keyboard (2)]
    ↳ Virtual core XTEST keyboard               id=5    [slave  keyboard (3)]
    ↳ Power Button                              id=6    [slave  keyboard (3)]
    ↳ Logitech MX Ergo                          id=15   [slave  keyboard (3)]

Consequently, grep "Logitech MX Ergo" ends up returning two values. The latter ends up being included as the first item in the mapping string and screws up all of your mouse buttons.

The fix is easy - just use grep's maximum-count argument, -m 1:

my_mouse_id=$(xinput | grep -m 1 "Logitech MX Ergo" | sed 's/^.*id=\([0-9]*\)[ \t].*$/\1/')
echo $my_mouse_id > ~/temp/my_mouse_id
xinput --set-button-map $my_mouse_id 1 2 3 4 5 6 7 8 2 10 11 12 13 14 15 16
  • Great tip; I've edited the answer to include it. Thanks! Commented Aug 15, 2018 at 17:26

I was able to change the mapping of my Logitech mouse's middle button to 'Return' using Easystroke Gesture Recognition which I downloaded from the Ubuntu Software Center. Edit: In the application, you would select Add Action, Name it, select the key type, click on Details and press Enter, hit Record Stroke, and during the prompt press down on the middle button.

  • Good catch. But what you described doesn't xork as you instructed: actually the middle button is the default button to put that app into 'gesture recognition mode': when pressing it, the app starts recognizing the gesture you're making. Yet, +1 because that app has a module to reveal mouse buttons IDs; this helps when we want to use xinput with buttons not showing up when using xinput list <devID>. Commented Nov 29, 2015 at 16:32
  • 1
    Oh, this came 1 year later - your answer worths +1 Commented Nov 29, 2015 at 17:37

Prior to 12.04 there was an easy graphical tool called "btnx" in the standard repository, which added as "Button properties" in System Configuration. Sadly however it was dropped. An "untrusted" PPA currently maintained for 14.04, 16.04 and 18.04 is here: https://launchpad.net/~oliverstar/+archive/ubuntu/ppa (found at https://launchpad.net/ubuntu/xenial/+source/btnx)

It will not integrate with System settings but is working quite fine on my laptop with a cheap 5-button-mouse. It can remap to keystrokes and commands too and the configuration is much more simple than with any other method!

  • I wonder if the tool is making the same changes, just in the background. ^_^ Commented Oct 10, 2018 at 0:15

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .