{"id":13545463,"url":"https://github.com/bulletmark/libinput-gestures","last_synced_at":"2025-05-13T22:00:16.947Z","repository":{"id":37430817,"uuid":"43460897","full_name":"bulletmark/libinput-gestures","owner":"bulletmark","description":"Actions gestures on your touchpad using libinput","archived":false,"fork":false,"pushed_at":"2025-05-08T03:43:23.000Z","size":328,"stargazers_count":4016,"open_issues_count":5,"forks_count":238,"subscribers_count":63,"default_branch":"master","last_synced_at":"2025-05-08T04:33:26.411Z","etag":null,"topics":["gestures","libinput","touchpad"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bulletmark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-30T21:41:28.000Z","updated_at":"2025-05-08T03:43:22.000Z","dependencies_parsed_at":"2023-01-31T02:30:34.364Z","dependency_job_id":"ea69c571-7f7e-47b0-96b3-e87468388205","html_url":"https://github.com/bulletmark/libinput-gestures","commit_stats":null,"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Flibinput-gestures","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Flibinput-gestures/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Flibinput-gestures/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Flibinput-gestures/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bulletmark","download_url":"https://codeload.github.com/bulletmark/libinput-gestures/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254036806,"owners_count":22003651,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gestures","libinput","touchpad"],"created_at":"2024-08-01T11:01:03.254Z","updated_at":"2025-05-13T22:00:16.842Z","avatar_url":"https://github.com/bulletmark.png","language":"Python","funding_links":[],"categories":["Python","Command Line Tools","HarmonyOS","others"],"sub_categories":["GUI tools","Windows Manager"],"readme":"### LIBINPUT-GESTURES\n[![AUR](https://img.shields.io/aur/version/libinput-gestures)](https://aur.archlinux.org/packages/libinput-gestures/)\n\n[Libinput-gestures][REPO] is a utility which reads [libinput\ngestures](https://wayland.freedesktop.org/libinput/doc/latest/gestures.html)\nfrom your touchpad and maps them to gestures you configure in a\nconfiguration file. Each gesture can be configured to activate a shell\ncommand which is typically an [_xdotool_][XDOTOOL] command to action\ndesktop/window/application keyboard combinations and commands. See the\nexamples in the provided `libinput-gestures.conf` file. My motivation\nfor creating this is to use triple swipe up/down to switch workspaces,\nand triple swipe right/left to go backwards/forwards in my browser, as\nper the default configuration.\n\nNote that [libinput does not interpret gestures for\ntouchscreens](https://wayland.freedesktop.org/libinput/doc/latest/gestures.html#touchscreen-gestures)\nso this utility can only be used for a touchpad, not a touchscreen.\n\nThis small and simple utility is only intended to be used temporarily\nuntil GNOME and other DE's action libinput gestures natively. It parses\nthe output of the _libinput list-devices_ and _libinput debug-events_\nutilities so is a little fragile to any version changes in their output\nformat.\n\nThis utility is developed and tested on Arch linux using the GNOME 3 DE\non Xorg and Wayland. It works somewhat incompletely on Wayland (via\nXWayland). See the WAYLAND section below and the comments in the default\n`libinput-gestures.conf` file. It has been [reported to work with\nKDE](http://www.lorenzobettini.it/2017/02/touchpad-gestures-in-linux-kde-with-libinput-gestures/).\nI am not sure how well this will work on all Linux systems and DE's etc.\n\nThe latest version and documentation is available at\nhttps://github.com/bulletmark/libinput-gestures.\n\n### INSTALLATION\n\nYou need _python_ 3.8 or later, _python2_ is not supported. You also need\n_libinput_ release 1.0 or later.\n\nYou **must be a member of the _input_ group** to have permission\nto read the touchpad device:\n\n    sudo gpasswd -a $USER input\n\nAfter executing the above command, reboot your system.\n\n**Note** adding yourself to the `input` group makes ALL `/dev/input`\ndevices readable by your user account and some consider this a security\nrisk. If you are concerned then consider adding a udev rule to apply a\ndynamic user ACL as [described\nhere](https://wiki.archlinux.org/title/Udev#Allowing_regular_users_to_use_devices),\nrather than adding yourself to the `input` group.\n\nMost/many users will require to install the following although neither are\nactual dependencies because some custom configurations will not require\nthem. If you are unsure initially, install both of them.\n\n|Prerequisite|Required for |\n|------------|-------------|\n|`wmctrl`    |Necessary for `_internal` command, as per default configuration|\n|`xdotool`   |Simulates keyboard and mouse actions for Xorg or XWayland based apps|\n\n    # E.g. On Arch:\n    sudo pacman -S wmctrl xdotool\n\n    # E.g. On Debian based systems, e.g. Ubuntu:\n    sudo apt-get install wmctrl xdotool\n\n    # E.g. On Fedora:\n    sudo dnf install wmctrl xdotool\n\nNOTE: Arch users can now just install [_libinput-gestures from the\nAUR_][AUR]. Then skip to the next CONFIGURATION section.\n\nDebian and Ubuntu users may also need to install `libinput-tools` if\nthat package exists in your release:\n\n    sudo apt-get install libinput-tools\n\nInstall this software:\n\n    git clone https://github.com/bulletmark/libinput-gestures.git\n    cd libinput-gestures\n    sudo ./libinput-gestures-setup install\n\n### CONFIGURATION\n\nIt is helpful to start by reading the documentation about [what libinput\ncalls gestures](https://wayland.freedesktop.org/libinput/doc/latest/gestures.html).\nMany users will be happy with the default configuration in which case\nyou can just type the following and you are ready to go:\n\n    libinput-gestures-setup autostart start\n\nOtherwise, if you want to create your own custom gestures etc, keep\nreading ..\n\nThe default gestures are in `/etc/libinput-gestures.conf`. If you want\nto create your own custom gestures then copy that file to\n`~/.config/libinput-gestures.conf` and edit it. There are many examples\nand options described in that file. The available gestures are:\n\n|Gesture               |Example Mapping |\n|-------               |--------------- |\n|`swipe up`            |GNOME/KDE/etc move to next workspace |\n|`swipe down`          |GNOME/KDE/etc move to prev workspace |\n|`swipe left`          |Web browser go forward |\n|`swipe right`         |Web browser go back |\n|`swipe left_up`       |Jump to next open web browser tab |\n|`swipe left_down`     |Jump to previous open web browser tab |\n|`swipe right_up`      |Close current web browser tab |\n|`swipe right_down`    |Reopen and jump to last closed web browser tab |\n|`pinch in`            |GNOME open/close overview |\n|`pinch out`           |GNOME open/close overview |\n|`pinch clockwise`     ||\n|`pinch anticlockwise` ||\n|`hold on`             |Open new web browser tab. See description of [hold gestures](#hold-gestures). |\n|`hold on+N` (for `N` seconds, e.g. 1.5) |After extra hold time delay, close browser tab. See description of [hold gestures](#hold-gestures). |\n\nNOTE: If you don't use \"natural\" scrolling direction for your touchpad\nthen you may want to swap the default left/right and up/down\nconfigurations.\n\nYou can choose to specify a specific finger count, typically [3 or more\nfingers for swipe](https://wayland.freedesktop.org/libinput/doc/latest/gestures.html#swipe-gestures),\nand [2 or more for pinch](https://wayland.freedesktop.org/libinput/doc/latest/gestures.html#pinch-gestures).\nIf a finger count is specified then the command is executed when exactly that\nnumber of fingers is used in the gesture. If not specified then the\ncommand is executed when that gesture is invoked with any number of\nfingers. Gestures specified with finger count have priority over the\nsame gesture specified without any finger count.\n\nOf course, 2 finger swipes and taps are already interpreted by your DE\nand apps [for scrolling](https://wayland.freedesktop.org/libinput/doc/latest/scrolling.html#two-finger-scrolling) etc.\n\nIMPORTANT: Test the program. Check for reported errors in your custom\ngestures, missing packages, etc:\n\n    # Ensure the program is stopped\n    libinput-gestures-setup stop\n\n    # Test to print out commands that would be executed:\n    libinput-gestures -d\n    (\u003cctrl-c\u003e to stop)\n\nConfirm that the correct commands are reported for your 3 finger\nswipe up/down/left/right gestures, and your 2 or 3 finger pinch\nin/out gestures. Some touchpads can also support 4 finger gestures.\nIf you have problems then follow the TROUBLESHOOTING steps below.\n\nApart from simple environment variable and `~` substitutions within the\nconfigured command name, `libinput-gestures` does not run the configured\ncommand under a shell so shell argument substitutions and expansions etc\nwill not be parsed. This is for efficiency and because most don't need\nit. This also means your `PATH` is not respected of course so you must\nspecify the full path to any command. If you need something more\ncomplicated, you can add your commands in an executable personal script,\ne.g. `~/bin/libinput-gestures.sh` with a `#!/bin/sh` shebang. Optionally\nthat script can take arguments. Run that script by hand until you get it\nworking then configure the script path as your command in your\n`libinput-gestures.conf`.\n\nIn most cases, `libinput-gestures` automatically determines your\ntouchpad device. However, you can specify it in your configuration file\nif needed. If you have multiple touchpads you can also specify\n`libinput-gestures` to use all devices. See the notes in the default\n`libinput-gestures.conf` file about the `device` configuration command.\n\n### STARTING AND STOPPING\n\nTo [re-]start the app immediately and also to enable it to start\nautomatically at login, just type the following:\n\n    libinput-gestures-setup stop desktop autostart start\n\nThe following commands are available:\n\nEnable the app to start automatically in the background when you\nlog in with:\n\n    libinput-gestures-setup autostart\n\nDisable the app from starting automatically with:\n\n    libinput-gestures-setup autostop\n\nStart the app immediately in the background:\n\n    libinput-gestures-setup start\n\nStop the background app immediately with:\n\n    libinput-gestures-setup stop\n\nRestart the app, e.g. to reload the configuration file, with:\n\n    libinput-gestures-setup restart\n\nCheck the status of the app with:\n\n    libinput-gestures-setup status\n\nYou can specify multiple user commands to `libinput-gestures-setup` to\naction in sequence.\n\nNote that on some uncommon systems then `libinput-gestures-setup start`\nmay fail to start the application returning you a message _Don't know\nhow to invoke libinput-gestures.desktop_. If you get this error message,\ninstall the dex package, preferably from your system packages\nrepository, and try again.\n\n### SYSTEMD USER SERVICE\n\nBy default, `libinput-gestures` is started with your DE as a desktop\napplication. There is also an option to start as a [systemd user\nservice](https://wiki.archlinux.org/title/Systemd/User). However, on\nsome systems this can be unreliable (on system restart, the application\nwill get started but occasionally will be unable to receive commands).\nIf you want to try it, type:\n\n    libinput-gestures-setup stop service autostart start\n\nYou can switch back to the desktop option with the command:\n\n    libinput-gestures-setup stop desktop autostart start\n\n### UPGRADE\n\n    # cd to source dir, as above\n    git pull\n    sudo ./libinput-gestures-setup install\n    libinput-gestures-setup restart\n\n### REMOVAL\n\n    libinput-gestures-setup stop autostop\n    sudo libinput-gestures-setup uninstall\n\n### WAYLAND AND OTHER NOTES\n\nThis utility exploits `xdotool` for many use cases which unfortunately\nonly works with X11/Xorg based applications. So `xdotool` shortcuts for\nthe desktop do not work under GNOME on Wayland which is the default\nsince GNOME 3.22. However, it is found that `wmctrl` desktop selection\ncommands do work under GNOME on Wayland (via XWayland) so this utility\nadds a built-in `_internal` command which can be used to switch\nworkspaces using the swipe commands. The `_internal` `ws_up` and\n`ws_down` commands use `wmctrl` to work out the current workspace and\nselect the next one. Since this works on both Wayland and Xorg, and with\nGNOME, KDE, and other EWMH compliant desktops, it is the default\nconfiguration command for swipe up and down commands in\n`libinput-gestures.conf`. See the comments in that file about other\noptions you can do with the `_internal` command. Unfortunately\n`_internal` does not work with Compiz for Ubuntu Unity desktop so also\nsee the explicit example there for Unity.\n\nOf course, `xdotool` commands do work via XWayland for Xorg based apps\nso, for example, page forward/back swipe gestures do work for Firefox\nand Chrome browsers when running on Wayland as per the default\nconfiguration.\n\nNote if you run `libinput-gestures` on GNOME with Wayland, be sure to\nchange or disable the your `libinput-gestures.conf` configured gestures\nto not clash with the native gestures.\n\nGNOME 3.38 and earlier on Wayland natively implements the following\ngestures:\n\n- 3 finger pinch opens/close the GNOME overview.\n- 4 finger swipe up/down changes workspaces\n\nGNOME 40-\u003e46 on Wayland natively implements the following\ngestures:\n\n- 3 finger swipe up/down opens the GNOME overview.\n- 3 finger swipe left/right changes workspaces\n\nNote that GNOME 40-\u003e46 does not use 4 finger gestures so you can freely\nassign them using `libinput-gestures`.\n\nGNOME 47 and above implements the same gestures as GNOME 40-\u003e46 but also\nduplicates those gestures to 4 finger gestures so you can't use them for\nlibinput-gestures unless you do one of the following to disable 3 finger\ngestures in GNOME.\n\n1. Install the [_Disable 3 Finger\n   Gestures_](https://extensions.gnome.org/extension/7403/disable-3-finger-gestures/)\n   GNOME shell extension (recommended).\n\n2. Patch `gnome-shell` to stop it using 3 finger gestures using this\n   [patch script](https://gist.github.com/bulletmark/0630478f98363adf584bbcfe8e527cb1).\n\nGNOME on Xorg does not natively implement any gestures.\n\n### EXTENDED GESTURES\n\nThey are not enabled in the default `libinput-gestures.conf`\nconfiguration file but you can enable extended gestures which augment\nthe gestures listed above in CONFIGURATION. See the commented out\nexamples in `libinput-gestures.conf`.\n\n- `swipe right_up` (e.g. jump to next open browser tab)\n- `swipe left_up` (e.g. jump to previous open browser tab)\n- `swipe left_down` (e.g. close current browser tab)\n- `swipe right_down` (e.g. reopen and jump to last closed browser tab)\n- `pinch clockwise`\n- `pinch anticlockwise`\n\nSo instead of just configuring the usual swipe up/down and left/right\neach at 90 degrees separation, you can add the above extra 4 swipes to\ngive a total of 8 swipe gestures each at 45 degrees separation. It works\nbetter than you may expect, at least after some practice. It means you\ncan completely manage browser tabs from your touchpad.\n\n### HOLD GESTURES\n\nLibinput version 1.19.0 added [HOLD\ngestures](https://wayland.freedesktop.org/libinput/doc/latest/gestures.html#hold-gestures)\nto augment the standard SWIPE and PINCH gestures. They are actioned with\n1 or more fingers after holding them for a small time period and are\nsimply set ON as a trigger.\n`libinput-gestures` interprets them to commands you can\nconfigure in your `libinput-gestures.conf`, e.g:\n\n    gesture hold on 4 xdotool key control+t\n\nThe above gesture will open a new tab in your browser if you rest 4\nfingers statically on the touchpad. If you don't specify a finger count\nthen the command is executed when any number of fingers are used for the\nhold.\n\nOptionally, you can configure a time delay on hold gestures to map\nlonger hold times to different commands. Any extra hold time can be\nspecified, as an integer or float value in decimal seconds. E.g. `on+1`\nis a hold + 1 extra second, `on+3.5` is a hold + 3.5 extra seconds, etc.\nThese can be configured in addition to `on` (which is effectively the\nsame as `on+0`), and also with different (or no specific) finger counts,\ne.g:\n\n    gesture hold on 4 xdotool key control+t\n    gesture hold on+2.2 4 xdotool key control+w\n\nThe above will configure a second 4 finger hold gesture which, after 2.2\nextra seconds to a normal hold, will close the current tab in your\nbrowser. You can configure as many hold gestures, with different times\nand finger counts (or no specific finger count), as you like but it will\nquickly get unworkable if you add too many, or with close delays.\n\nTo get an idea of suitable hold times to configure, comment out all hold\ngestures in your configuration file `libinput-gestures.conf` and run\nwith debug output. I.e. run `libinput-gestures -d` in a terminal window\n(you may have to temporarily disable `libinput-gestures` first by\nrunning `libinput-gestures-setup stop`). Then experiment with different\nholds which will print the times to the screen so you can choose what to\nconfigure for your hold gestures. Run `libinput-gestures-setup restart`\nto restart `libinput-gestures` after updating your configuration.\n\n### AUTOMATIC STOP/RESTART ON D-BUS EVENTS SUCH AS SUSPEND\n\nThere are some situations where you may want to automatically stop,\nstart, or restart `libinput-gestures`. E.g. some touchpads have a\nproblem which causes `libinput-gestures` (actually the underlying\n`libinput debug-events`) to hang after resuming from a system suspend so\nthose users want to stop `libinput-gestures` when a system goes into\nsuspend and then start it again with resuming. You can use a companion\nprogram [`dbus-action`][DBUS] to\ndo this. See the example configuration for `libinput-gestures` in the\ndefault [`dbus-action`][DBUS] [configuration\nfile](https://github.com/bulletmark/dbus-action/blob/master/dbus-action.conf).\n\nThe [`dbus-action`][DBUS] utility can also be used any similar\nsituation, e.g. when you remove/insert a detachable touchpad. It can be\nused to stop, start, or restart `libinput-gestures` on any D-Bus event.\n\n### TROUBLESHOOTING\n\nPlease don't raise a github issue but provide little information about\nyour problem, and please don't raise an issue until you have considered\nall the following steps. **If you raise an issue ALWAYS include the\noutput of `libinput-gestures -l` to show the environment and\nconfiguration you are using, regardless of what the issue is about**.\n\n1. Ensure you are running the latest version from the\n   [libinput-gestures github repository][REPO] or from the [Arch AUR][AUR].\n\n2. Ensure you have followed the installation instructions here\n   carefully. The most common mistake is that you have not added your\n   user to the _input_ group and rebooted your system as described\n   above.\n\n3. Perhaps temporarily remove your custom configuration to try with the\n   default configuration.\n\n4. Run `libinput-gestures-setup status` and confirm it reports the set\n   up that you expect.\n\n5. Run `libinput-gestures` on the command line in debug mode while\n   performing some 3 and 4 finger left/right/up/down swipes, and some\n   pinch in/outs. In debug mode, configured commands are not executed,\n   they are merely output to the screen:\n   ````\n\tlibinput-gestures-setup stop\n\tlibinput-gestures -d\n\t(\u003cctrl-c\u003e to stop)\n   ````\n\n6. Run `libinput-gestures` in raw mode by repeating the same commands as\n   above step but use the `-r` (`--raw`) switch instead of `-d`\n   (`--debug`). Raw mode does nothing more than echo the raw gesture\n   events received from `libinput debug-events`. You should see the\n   following types of events when you move your fingers:\n\n   - 1 and 2 finger movements should output `POINTER_*` type events\n   - 3 (and above) finger movements should output `GESTURE_*` type events.\n\n   If you do not see any `GESTURE_*` events then unfortunately your\n   touchpad and/or libinput does not report multi-finger gestures so\n   `libinput-gestures` can not work. The discrimination of\n   gestures is done completely within libinput, before they get passed\n   to `libinput-gestures`.\n\n7. Search the web for Linux kernel and/or libinput issues relating to\n   your specific touchpad device and/or laptop/pc. Update your BIOS if\n   possible.\n\n8. Be sure that a configured external command works exactly how you want\n   when you run it directly on the command line, **before** you configure\n   it for `libinput-gestures`. E.g. run `xdotool` manually and\n   experiment with various arguments to work out exactly what arguments\n   it requires to do what you want, and only then add that command +\n   arguments to your custom configuration in\n   `~/.config/libinput-gestures.conf`. Clearly, if the your manual\n   `xdotool` command does not work correctly then there is no point\n   raising an `libinput-gestures` issue about it!\n\n9. **If you raise an issue, always include the output of\n   `libinput-gestures -l` to show the environment and configuration you\n   are using**. If appropriate, also paste the output from steps 4 and 5\n   above. If your device is not being recognised by `libinput-gestures`\n   at all, paste the complete output of `libinput list-devices`\n   (`libinput-list-devices` on libinput \u003c v1.8).\n\n### LICENSE\n\nCopyright (C) 2015 Mark Blakeney. This program is distributed under the\nterms of the GNU General Public License.\nThis program is free software: you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation, either version 3 of the License, or any later\nversion.\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General\nPublic License at \u003chttps://www.gnu.org/licenses/\u003e for more details.\n\n[REPO]: https://github.com/bulletmark/libinput-gestures/\n[DBUS]: https://github.com/bulletmark/dbus-action/\n[AUR]: https://aur.archlinux.org/packages/libinput-gestures/\n[XDOTOOL]: https://www.semicomplete.com/projects/xdotool/\n\n\u003c!-- vim: se ai syn=markdown: --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletmark%2Flibinput-gestures","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbulletmark%2Flibinput-gestures","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletmark%2Flibinput-gestures/lists"}