# Fusuma: Multitouch Gesture Recognition for Linux Touchpads

> Fusuma is a Ruby-based daemon that maps libinput touchpad gestures to arbitrary shell commands on Linux. It solves the long-standing gap between macOS-style multitouch workflows and standard Linux desktop environments, though it requires a specific group permission change that carries a small security implication.

**iberianpig/fusuma** — Multitouch gestures with libinput driver on Linux

- Repository: https://github.com/iberianpig/fusuma
- Stars: 3,895 · Forks: 145
- Language: Ruby
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/iberianpig-fusuma

## The Problem Fusuma Addresses on Linux Touchpads

Standard Linux desktop environments do not expose a general API for mapping touchpad gestures to arbitrary actions. A three-finger swipe might be claimed by the compositor for workspace switching, but only in the direction the compositor chose. Fusuma reads raw libinput events directly, which means it intercepts gestures before the compositor does and dispatches whatever shell command you configure. This works across GNOME, KDE Plasma, i3, Cinnamon, and any other desktop that does not lock down libinput access entirely.

The trade-off is real: because Fusuma reads /dev/input/ directly, your user account must be a member of the input group. The README states plainly that this makes /dev/input/ readable to your account, and it recommends thinking through whether that is acceptable if privacy or OS stability is a concern. The project does not offer a polkit-based alternative; group membership is the only documented path.

## How Fusuma Reads and Dispatches Gestures

Fusuma runs as a daemon in userspace. It opens the touchpad device node through the libinput library (version 1.0 or later is required), listens for gesture events, and evaluates them against the rules in your YAML configuration. When a gesture matches a rule, Fusuma forks and runs the shell command in the `command:` field.

The gesture vocabulary covers swipe (3 and 4 fingers, four directions, with begin/update/end phases), pinch (2 to 4 fingers, in/out, with begin/update/end phases), rotate (2 to 4 fingers, clockwise and counterclockwise, with begin/update/end phases), and hold (1 to 4 fingers, begin/end/cancelled). Hold requires libinput 1.19.0 or later. Each gesture phase is addressable separately, so you can run one command when a swipe begins and a different one when it ends.

Fusuma does not synthesize desktop events internally. It delegates all actual work to whatever command you supply. The most common choice is xdotool, which sends keyboard shortcuts to the active window or the window manager. On GNOME with Wayland, xdotool may not function; the README references this in the GNOME section but does not document a Wayland-native alternative.

## Installing Fusuma on Debian, Arch, and Fedora

The installation sequence is consistent across distributions: install libinput tools and Ruby, install the gem, optionally install xdotool, then add your user to the input group.

On Debian, Ubuntu, and derivatives:

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

On Arch-based distributions, the Arch Wiki recommends installing gems per-user rather than system-wide. Arch users can also install the AUR package `ruby-fusuma`, though the README notes this community package is not officially supported and issues arising from it should not be filed against the project.

```bash
sudo pacman -Syu libinput-tools
sudo pacman -Syu ruby
sudo gem install fusuma
```

On Fedora:

```bash
sudo dnf install libinput
sudo dnf install ruby
sudo gem install fusuma
```

After installing on any distribution, add your user to the input group and apply the change without logging out:

```bash
sudo gpasswd -a $USER input
newgrp input
```

On GNOME, if touchpad events are not reaching the desktop, enable them with:

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

Once the group change is in effect, run Fusuma with:

```bash
fusuma
```

## Writing a YAML Gesture Configuration

Fusuma reads its configuration from `~/.config/fusuma/config.yml`. The directory must be created manually if it does not exist:

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

The YAML file is structured by gesture type, finger count, and direction. A three-finger left swipe moving forward in browser history, and a four-finger swipe switching workspaces in Ubuntu, looks like this:

```yaml
swipe:
  3:
    left:
      command: "xdotool key alt+Right"
    right:
      command: "xdotool key alt+Left"
    up:
      command: "xdotool key super"
    down:
      command: "xdotool key super"
  4:
    left:
      command: "xdotool key ctrl+alt+Down"
    right:
      command: "xdotool key ctrl+alt+Up"
```

YAML indentation uses spaces, not tabs. The `command:` value is passed directly to the shell, so any valid shell command works. The project's wiki contains contributed configurations for Ubuntu, elementary OS, i3, KDE mimicking macOS, Pop!_OS with Cinnamon, and other setups, all editable by the community.

## Extending Fusuma with Its Plugin System

Fusuma exposes a plugin system for functionality that goes beyond running a single shell command. The README links to the plugin system documentation in the repository but does not enumerate every available plugin inline. Plugin names follow a `fusuma-plugin-*` naming convention on RubyGems. On Arch, the AUR follows a matching `ruby-fusuma-replacewithnameofplugin` scheme for community-built plugin packages.

Sensitivity tuning is built into the core configuration. Thresholds and intervals for each gesture type can be adjusted in the YAML file to reduce false triggering on slower or more deliberate touches. The README does not specify the exact key names for sensitivity settings, but describes them as adjustable parameters that affect gesture recognition precision.

## Limitations and Cases Where Fusuma Falls Short

Fusuma is a wrong fit in several scenarios. On Wayland compositors that block direct libinput access, Fusuma may fail to see events at all; the README does not document a Wayland-native input path. In environments where membership in the input group is not permitted due to organizational security policy, there is no alternative installation method.

The project has no GitHub releases. Updates are distributed through RubyGems. Users on distributions where the system Ruby is tightly managed (such as Arch, where gems default to per-user installation) may encounter PATH issues if the gem binary lands in ~/.gem/ruby/bin/ and that path is not in the session PATH.

Fusuma does not process gestures from mice or USB trackpads unless libinput reports them as touch devices. Bluetooth touchpads may work, but the README does not document their behavior.

## Comparing Fusuma to libinput-gestures

The most direct alternative is libinput-gestures, a Python-based tool that reads libinput debug output from the command line rather than calling the libinput C API directly. Both tools require the input group and both dispatch shell commands. The difference is in architecture: libinput-gestures parses the text output of `libinput debug-events`, which is a stable but unofficial interface, while Fusuma uses the libinput C library through Ruby bindings, which is closer to the documented API.

Fusuma has a richer built-in phase system (begin/update/end per gesture) that libinput-gestures does not expose by default. Fusuma's configuration is also YAML-only, while libinput-gestures uses its own INI-style config. Neither tool runs on Wayland without workarounds; both depend on the same underlying libinput permission model.

The last push to Fusuma was on 2026-07-10, so it is receiving updates.

## Conclusion

Fusuma is the right tool for Linux laptop users who want macOS-style multitouch gestures without switching desktops. It works across distributions and desktops that support Qt 6 or GNOME. Before adopting it, verify that your touchpad is recognized by libinput 1.0 or later, add your user to the input group, and decide whether the broadened read access to /dev/input/ is acceptable in your security context. For users on Wayland-only sessions without XDG integration, the README does not document whether xdotool commands function; check the wiki page for your desktop before committing to xdotool-based mappings.

## FAQ

### How do I install Fusuma on Linux?

Install libinput-tools and Ruby through your distribution's package manager, then run `sudo gem install fusuma`. After that, add your user to the input group with `sudo gpasswd -a $USER input` and apply the change with `newgrp input`.

### What is Fusuma in the context of Linux?

In this context, Fusuma is a Ruby daemon that reads multitouch gesture events from a Linux touchpad via libinput and maps them to shell commands defined in a YAML configuration file.

### How does Fusuma compare to libinput-gestures?

Both tools require input group membership and dispatch shell commands on gestures. Fusuma uses the libinput C API through Ruby bindings and supports begin/update/end gesture phases; libinput-gestures parses the text output of `libinput debug-events` and lacks per-phase events by default.

## Sources

- [iberianpig/fusuma on GitHub](https://github.com/iberianpig/fusuma)
- [Issues](https://github.com/iberianpig/fusuma/issues)
- [License: MIT](https://github.com/iberianpig/fusuma/blob/main/LICENSE)
- [README](https://github.com/iberianpig/fusuma/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/iberianpig-fusuma