This page describes how to configure Ubuntu to fully utilize a mouse with multiple buttons, wheels, and other controls.

Before You Begin

It's important to note that Ubuntu considers a standard two button, scroll/click-wheel mouse to have five buttons. Each main button (left and right) count as one, the downward click on the wheel counts as another, and the up/down scrolling also count as one each (2+1+2=5).

Beyond the Basics

If you have installed the GNOME environment (default for Ubuntu) you already have the software needed to get the "6th" and "7th" mouse buttons working (forward/backward on most mice)!


Note that xorg X Input system cannot bind a combination of more than one mouse button to a certain action. For example, it is not possible to bind left-clicking while simultaneously scrolling up to a specific action. So the rule of thumb is one button for one action, unless the button is combined with the keyboard modifier keys (Ctrl, Alt, Super,...)

Remapping buttons

Some pointing devices have a strange button mapping, so need some tweaking to match X's perception of things. Such tweaking can be performed at runtime with xinput - find your device in xinput list and run xinput set-button-map <device name> 1 2 3 6 7, replacing those numbers with your required button mapping. You might be able to find it by searching for other people with the same hardware, or you might need to play around and see what works. To find the mappings currently applied, you can use xinput test <id>, where <id> is your device's id number found with xinput list.

Mapping More Buttons

The key to being able to program mouse buttons beyond the seven already discussed is to install imwheel (from the Universe repository). Imwheel will enable you to define application-specific actions to your additional mouse buttons.

  1. Download and install imwheel using Synaptic, Adept, or apt-get
  2. Modify your /etc/X11/imwheel/imwheelrc or ~/.imwheelrc file to tell imwheel what to do with a mouse click when it happens in a particular application. See the Wikis referenced below for details on what you can do with your imwheelrc or .imwheelrc file. NOTE: You can use modifications to the ~/.imwheelrc to limit imwheel behavior to specific users on your system.

  3. Finally, if desired, tell X11 to run imwheel whenever X11 is started (modifying /etc/X11/Xsession.d/60imwheel_start-imwheel and changing IMWHEEL_START=0 to =1 in /etc/X11/imwheel/startup.conf). Alternately, you can start imwheel manually.

Before You Proceed

Before any further editing to xorg.conf or .imwheelrc, it might be helpful to check your mouse button mappings.

Run imwheel -c from a terminal window for imwheel's graphical UI. Pressing the GrabWheelAction button and then one of your mouse's buttons should cause imwheel to show the button's default mapping. In practice, this seemed somewhat inconsistent, but results may differ depending on your particular mouse.

The information you glean from this test could prove helpful if your mouse doesn't have traditional button mappings. If, for example, your side mouse buttons map to the standard left and right (1 and 2) positions, and you wanted these side buttons to control Firefox's Back and Forward buttons, you would use the following .imwheelrc entry for Firefox.



Frequently, the best way to learn is to look at what works for other people. Here are some examples of working imwheelrc files. Compare these to your own to help you troubleshoot and test out new configurations.


Here is an example of what a portion of my .imwheelrc looks like:

# Flip between browser tabs
None, Left, Control_L|Page_Up
None, Right, Control_L|Page_Down

If you'd like to customize your mouse buttons for additional applications, just add more entries like this to the imwheelrc file.

Useful links

CategoryHardware CategoryXwindowSystem

ManyButtonsMouseHowto (last edited 2017-09-13 01:43:51 by ckimes)