Switch the Active X Pointer Safely with xsetpointer

Two pointing devices are fighting over the same cursor, and xsetpointer is the command that decides which one is in charge. It lists the X Input devices visible to your session, makes one of them the main pointer, and restores core pointer events if you disabled them along the way. This is a session-level change, not a system configuration change.

Allow about ten minutes. You need the x11-xserver-utils package, a running X server, and permission to connect to that server. These examples use the installed package version 7.7+10build2. Wayland-only sessions are outside this command's scope.

1. Confirm the command and display

Check which executable will run, then inspect the display variable your shell is using:

$ command -v xsetpointer
/usr/bin/xsetpointer
$ printf 'DISPLAY=%s\n' "${DISPLAY-}"

The second line is host-specific: it should contain the display name for your active X session, often something like :0. If it is empty, do not guess a value. Run the command from a terminal that belongs to the X session, or set DISPLAY and the matching X authorisation the same way your desktop session does.

2. List the available input devices

Ask the X server for its device names:

$ xsetpointer -l
# device lines are supplied by your X server
$ printf 'exit status: %s\n' "$?"
exit status: 0

The output is deliberately not shown as a fixed list here: device names depend on the server, drivers and hardware attached to this session. Copy the exact name of the device you want from this output. Do not substitute a Linux path such as /dev/input/event0; xsetpointer expects an X Input device name.

The -l option only lists devices; it does not select one. If the command fails, go back to step 1 and fix the display connection before changing anything.

3. Select one device as the main pointer

Pass the exact X device name as the sole argument, quoted because names can contain spaces or punctuation:

$ xsetpointer 'EXACT DEVICE NAME FROM -l'
$ printf 'exit status: %s\n' "$?"
exit status: 0

Replace EXACT DEVICE NAME FROM -l with a real name. A successful status means the X server accepted the request; the command prints no success message, so the exit status is your checkpoint here.

Move the physical device or click in a harmless area to check the result. If the wrong device became active, repeat step 2, pick the right name, and run this step again. There is no universal undo name: restoring the previous device needs the previous name from your notes or from the device list.

4. Understand core pointer events

Some X servers implement a virtual core pointer. For those, -c stops it sending core input events, and +c switches that back on:

$ xsetpointer -c
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ xsetpointer +c
$ printf 'exit status: %s\n' "$?"
exit status: 0

These are state-changing commands. Disabling core events can stop ordinary pointer-driven desktop controls from receiving input at all. Use -c only for a specific test or compatibility reason, and keep the recovery command xsetpointer +c ready before you begin. The option only affects servers that implement a virtual core pointer; it is not a general switch for every input stack.

5. Keep the change temporary and reviewable

xsetpointer changes only the live X server state. The manpage describes no configuration file, boot setting or persistent profile for this command. Treat a successful selection as a change to the current session, and do not put an unreviewed device name into a login script or desktop startup file.

For a script, check the command's status and keep device names as explicit data:

device_name='EXACT DEVICE NAME FROM -l'
if xsetpointer "$device_name"; then
    printf 'main pointer request accepted\n'
else
    status=$?
    printf 'xsetpointer failed with status %s\n' "$status" >&2
    exit "$status"
fi

Do not parse a guessed line number out of -l, and do not treat a command that cannot connect to the X server as a device-selection failure: those are separate problems with separate fixes.

6. Diagnose the common failures

If xsetpointer -l reports that it cannot connect, check DISPLAY and X authorisation from the same terminal context as the desktop. If the device is missing from the list, the X server has not exposed it under the name you supplied, so check the session type and input-device setup before trying a different spelling.

If a quoted name still fails, copy it again from the current list. Hardware can disappear between listing and selection, especially after a receiver is unplugged. Avoid repeatedly selecting devices while troubleshooting a live desktop, because each successful request changes where pointer events go.

You do not need elevated privileges for listing, selection or toggling core events. If a desktop policy blocks access to the X server, address that through the session's normal administration process rather than weakening access controls by exposing the display to other users.