Fusuma: Multitouch Gestures on Linux with libinput and a YAML File

What Fusuma solves, and who it is actually for

On Linux, touchpad gesture recognition is not a given. Whether a three-finger swipe switches workspaces depends on the desktop environment, and the mapping usually stops at whatever the settings panel exposes. Fusuma takes the other route: it reads the touchpad through libinput and runs the command you attach to each gesture. The README describes it as a tool that enables multitouch gesture recognition on Linux, with gestures like swipes and pinches on laptops and devices with touchpads.

The audience is narrow and specific. You need a Linux machine with a touchpad, a working libinput stack, Ruby, and a willingness to write YAML by hand. The payoff is that any gesture can trigger any command, so the ceiling is your shell, not a settings dialog. If your desktop environment already handles every gesture you care about, Fusuma adds a daemon and a config file for nothing. The project name is the Japanese word for a sliding door, which is why searches for Fusuma return as much about interior design as about software.

How libinput events become shell commands

The pipeline has three visible stages. libinput reports raw touchpad events. Fusuma interprets them as gestures, using thresholds and intervals that the README lists under sensitivity settings, and then dispatches the command bound to that gesture in your YAML file. The README states that Fusuma reads the touchpad device directly, which is exactly why the input group permission matters: the process needs read access to the device node, not a privileged desktop API.

Gesture recognition is deliberately coarse-grained. Swipes support three and four fingers in four directions; pinches support two, three and four fingers with in and out; rotation supports two, three and four fingers clockwise and counterclockwise; hold supports one to four fingers. Each gesture type exposes begin, update and end events, except hold, which exposes begin, end and cancelled. That event split is the part worth understanding: begin and end fire once at the edges of a gesture, while update fires continuously, so binding a command to update runs it repeatedly for the duration of the movement. The README's own Ubuntu example binds swipe directions to xdotool key presses, which are one-shot actions and therefore fit the end-of-gesture model. A command that opens an application belongs on begin or end, not update.

Hold is the newest of the four and carries a version dependency the others do not: the README requires libinput 1.19.0 or later for it. On a distribution shipping an older libinput, hold is simply unavailable, and the config key for it will not do anything useful.

Installing Fusuma on Debian, Arch and Fedora

Every installation path starts with the same permission step, and the README marks it as mandatory: you must be a member of the input group to read the touchpad. The command adds your user to that group, and newgrp applies the change in the current shell without logging out.

sudo gpasswd -a $USER input
newgrp input

The README is explicit about the trade-off here: this makes /dev/input/ readable, and it tells you to consider that a heads-up if that is a problem for privacy or security reasons, or if it causes other parts of your OS to misbehave. That is a real widening of access, not a formality, and it is the first thing to weigh before installing.

On Debian-based distributions the README lists four steps: install libinput-tools, install Ruby, install the gem, and optionally install xdotool for sending shortcuts. The README requires libinput release 1.0 or later.

sudo apt-get install libinput-tools
sudo apt-get install ruby
sudo gem install fusuma
sudo apt-get install xdotool

The Arch instructions follow the same shape with pacman, and the README notes that on Arch, gem installs go per-user into ~/.gem/ruby/ by default rather than system-wide. Fedora uses dnf for libinput, ruby and the optional xdotool. On Arch there is also an AUR package named ruby-fusuma, which the README describes as community-built and not officially supported; plugins follow the naming scheme ruby-fusuma-replacewithnameofplugin. If you install that way, the README says you are on your own and asks you not to file issues about it.

For GNOME users there is a separate step, because the desktop has to be told to receive touchpad events at all:

gsettings set org.gnome.desktop.peripherals.touchpad send-events enabled

Running Fusuma is a single command with no arguments:

fusuma

Before that will do anything, the config file has to exist. The README notes that you need to create the ~/.config/fusuma directory yourself if it is not there yet.

mkdir -p ~/.config/fusuma
nano ~/.config/fusuma/config.yml

The README's Ubuntu example maps three-finger swipes to browser history and the activity view, four-finger swipes to workspace switching, pinch to zoom, and a four-finger hold to the activity view:

swipe:
  3:
    left:
      command: "xdotool key alt+Right" # History forward
    right:
      command: "xdotool key alt+Left" # History back
pinch:
  in:
    command: "xdotool keydown ctrl click 4 keyup ctrl" # Zoom in
  out:
    command: "xdotool keydown ctrl click 5 keyup ctrl" # Zoom out
hold:
  4:
    command: "xdotool key super" # Activity

Two YAML details from the README will bite you if you ignore them: indentation denotes structure, and tabs are not valid indentation. A config file that mixes tabs and spaces will not parse the way you intended. Updating later is a single command:

sudo gem update fusuma

Where Fusuma fails or is the wrong tool

The input group requirement is the biggest one, and the README does not soften it. If you are on a shared or managed machine where /dev/input/ must stay unreadable, Fusuma is not the right choice, and the README says so in its own words rather than leaving you to discover it.

Configuration is text-only. There is no GUI, no gesture recorder, and no validation step described in the README before you launch the daemon. A typo in the YAML indentation produces behaviour that looks like a recognition problem, and the README's sensitivity settings are the only documented lever for tuning how a gesture is detected. Expect to iterate by editing the file and restarting.

The command layer is a second failure surface. Because actions are shell commands, a gesture bound to xdotool depends on xdotool being installed, and the README marks that package as optional, which means a config copied from the wiki can silently do nothing on a machine without it. Commands bound to update fire repeatedly, so a heavy command there will spawn processes for as long as your fingers move.

Finally, hold is gated on libinput 1.19.0 or later. On older stacks the gesture type is documented but not usable, and nothing in the README suggests a fallback. If hold is the reason you are interested, check your libinput version before you write the config.

Fusuma compared with libinput gestures and Byobu

The most direct alternative is the libinput gestures command, which comes with libinput-tools. It reads the same device events and runs a command per gesture, but it is configured through command-line flags at invocation rather than through a persistent YAML file, and it does not ship the plugin system or the sensitivity settings that Fusuma documents. If you want one or two gestures and no daemon, that is a smaller footprint. If you want a config file you can version and extend, Fusuma is the more structured option. The two are not layered: both read the touchpad through libinput, so running them together means two processes competing for the same events.

Byobu is a different kind of comparison, and the one people search for is often a name collision rather than a genuine substitute. Byobu is a terminal multiplexer wrapper for tmux or screen; it has nothing to do with touchpad input. If a search for Fusuma against Byobu brought you here, the two do not overlap, and choosing between them is not a decision about gesture recognition at all.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-07-10, roughly two and a half months before this writing. That is recent, but the repository has no published releases, so the practical upgrade story is the gem itself: sudo gem update fusuma. Because RubyGems installs into whichever gem path your setup uses, the Arch note about per-user versus system-wide gems applies to upgrades too, and a system-wide install needs sudo while a per-user one does not.

The licence is MIT, which permits use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence with no copyleft obligation on your config file or the commands you bind. This is a description of the licence text, not legal advice; if you are redistributing Fusuma inside a product, read the LICENSE file in the repository root.

The upgrade cost that matters more than the gem version is the config file. Gesture keys and event names are the interface you write against, and nothing in the README promises they will not change. Keeping ~/.config/fusuma/config.yml under version control is the cheap insurance, and it costs you nothing but a git init in that directory.

Editorial conclusion

Adopt Fusuma if you run Linux on a laptop with a touchpad, you are comfortable editing YAML, and your desktop environment does not already give you the gesture mapping you want. Skip it if you cannot or will not join the input group, if you are on Wayland and expect the same behaviour, or if you want a graphical settings panel rather than a config file. Before installing, confirm your libinput is release 1.0 or later, and check that libinput-tools is available for your distribution; the hold gesture additionally requires libinput 1.19.0 or later, so verify your version first if you plan to use it.

Frequently asked questions

Official sources

1. iberianpig/fusuma on GitHub
2. Issues
3. License: MIT
4. README