Five Pinch documentation

Quick start

Five Pinch adds five-finger pinch actions to MacBook trackpads and other Linux touchpads on GNOME 50 with Wayland, provided the hardware meets the contact-tracking requirements. Pinch inward to open your application grid; spread outward to close it. Both directions are configurable.

1. Check compatibility and install the package.
2. Save your work, log out, and log back in.
3. Open Five Pinch Settings. Click Enable if prompted.
4. Choose your two actions, select a sensitivity, and enable gestures.

This documentation matches version 0.7.2, including its simplified settings. Extension Manager is optional; use Five Pinch Settings directly.

Requirements & hardware

• GNOME Shell 50, Wayland. Ubuntu 26.04 with its default GNOME desktop is the reference environment. Other GNOME versions, X11, KDE, Windows, and macOS are not supported by this release.
• A touchpad with five independently tracked positions. Counting five fingers alone is not enough. Linux Protocol B contact slots, tracking IDs, valid X/Y ranges, and session read access are required.

Tested: 2017 MacBook Pro, Apple SPI Touchpad (001c:06cb:0557), Ubuntu 26.04, GNOME 50, Wayland. Gesture actions and the rinertia compatibility fix were confirmed by the reference user.

There is no brand, bus, or model allowlist. Other MacBooks and non-Apple touchpads can be tried. They are not verified simply because installation succeeds. Unsupported capabilities are reported in Diagnostics; they do not block package installation.

To check your session:

gnome-shell --version
echo "$XDG_SESSION_TYPE"

gnome-shell should report version 50, and the session command should print wayland.

Install

Recommended: signed APT repository

Open Terminal and run the following. You need curl and gpg; if missing, run sudo apt update && sudo apt install curl gpg first.

curl -fL https://nymeriq.github.io/five-pinch/setup-apt.sh -o /tmp/five-pinch-apt-setup.sh
sudo sh /tmp/five-pinch-apt-setup.sh
sudo apt update
sudo apt install five-pinch

APT installs the application's required dependencies. A separate Extension Manager application is not required.

Standalone .deb

Download the release package, open Terminal in its folder, and run:

sudo apt install ./five-pinch_0.7.2_all.deb

Use the actual downloaded filename. Installing a standalone file does not add the update repository. Log out and back in after installation.

Set up your gestures

Open Five Pinch Settings from your applications. An active installation opens preferences directly. If the extension is inactive, click Enable first. Recognition and actions start disabled on a fresh installation; upgrades retain your existing choices.

1. Set both directions to Detect only and switch on Enable gestures.
2. Place five fingers on the pad and make an inward or outward pinch. Lift all fingers before the next attempt.
3. Expand Diagnostics and check Last gesture.
4. Once detection works, choose Pinch in → Open app grid and Pinch out → Close app grid.
5. Start with Balanced. Try Sensitive if smaller movements are missed.

You do not need to enter a device path for normal use. Leave Advanced → Touchpad empty for automatic selection.

Previous manual installation

A user-installed copy can override the Debian package. The launcher offers Use packaged version when it finds one. It disables and backs up that copy under ~/.local/state/five-pinch/backups/ (or your XDG state location), while preserving gesture settings. Log out and back in after switching. Unexpected paths or symlinks are not migrated.

Gesture actions

Choose each direction independently. The dropdown labels map to these behaviors:

App grid and overview are separate states. Use the matching close action. Each physical hand-contact cycle produces at most one pinch action; lift all fingers to start another.

Sensitivity

Sensitivity changes only Five Pinch's own recognition thresholds. It does not globally adjust GNOME gestures, scroll speed, or pointer acceleration.

Both the scale and distance threshold must be met. Distances use millimetres when physical resolution is supplied. Otherwise the reader uses an approximate normalized 100 × 100 space; the values are then relative units, not millimetres.

Changes apply immediately. Lift all fingers after changing modes. If unintended pinches occur, try Balanced or Original. Sensitive keeps the internal stored value relaxed for upgrade compatibility.

This is action recognition, not finger-following animation. A recognized pinch triggers a GNOME action; the app grid does not continuously scale with your fingers.

Gesture & rinertia protection

Swipe protection

Under Advanced, Swipe protection guards the ending of an interaction that reaches five physical contacts. It filters new native three/four-finger swipe sequences on that same touchpad while fingers are being lifted. Independent interactions that never reach five contacts do not arm it.

A swipe already underway before the reader notification reaches GNOME is left alone to avoid interrupting an active animation. This is a bounded, best-effort guard, not a guarantee against every gesture-extension conflict.

rinertia protection

Some users run rinertia for momentum scrolling. During the reference investigation, it emitted leftover scrolls through its virtual mouse while the app grid was closing. GNOME interpreted those scrolls as workspace navigation, even though no native swipe had occurred.

rinertia protection automatically matches scroll events from the running device named rinertia Virtual Device. It filters those events during a five-contact interaction and its momentum tail.

• The rinertia process is never stopped, restarted, installed, or reconfigured.
• Without the matching virtual device, there is nothing to intercept. Other mice pass through.
• A new physical touchpad contact cycle clears the old momentum guard, including for ordinary one-to-four-finger interactions.
• After full hand lift, a 120 ms gap in virtual scroll events ends protection. A hard two-second limit also ends the momentum phase. The active contact phase has a three-second watchdog.
• Disabling the extension, pausing recognition, locking the session, or restarting the reader clears the guard.

Both protections are on by default and can be switched off independently. The fix was confirmed on the reference MacBook Pro. Different rinertia device names, multiple touchpads feeding a shared virtual pointer, and IPC timing can still create edge cases. Check Diagnostics → Protection when reporting a conflict.

Choose a touchpad

Automatic mode scans input devices classified by Linux udev as touchpads and chooses the first usable one. It skips candidates that cannot provide the required data. It does not scan keyboard event streams.

For multiple touchpads, enter a full device path in Advanced → Touchpad, such as /dev/input/event7. It is not a device name, vendor/product ID, or just event7.

sudo libinput list-devices

Install libinput-tools if the command is missing. Find your touchpad's Device section and copy its Kernel path. Do not select a keyboard or mouse entry. Event numbers can change after reconnecting or rebooting; clear the field to restore automatic selection if needed.

How Five Pinch works

The Python reader reconstructs complete Linux multitouch frames. It tracks five stable contact IDs and compares the distances of all ten finger pairs. A pinch needs a median scale change, a minimum distance change, and movement in the same direction for at least seven pairs.

Contact identity changes, clicks, invalid frames, timeouts, and input loss prevent uncertain candidates from becoming actions. Existing three/four-finger gestures remain GNOME's responsibility, subject to the scoped protection described above.

The extension supervises the reader over private pipes and a one-second heartbeat lease. The reader closes and exits if its parent disappears or its lease expires. There is no permanent root daemon, standalone autostart service, exclusive input grab, virtual input injection, firmware change, driver replacement, or libinput patch.

Recognition pauses for locked/inactive sessions, sleep and long Shell stalls. Typing triggers a short pause, but typing/palm/thumb handling is not equivalent to libinput's full filtering and is not validated in every application.

What is installed or stored?

• A GNOME extension, supervised Python reader, settings launcher, reset tool, and icon, all owned by the Debian package.
• A udev rule adding standard session access only to devices classified as touchpads. It does not add you to the broad input group or make event nodes world-readable. Standard session ACLs may include write access; the reader itself opens the pad read-only.
• Your choices under /org/gnome/shell/extensions/five-pinch/ in your user settings.
• The three APT setup files, if you chose the repository.

Normal operation stores status and the latest gesture, not raw contact history. Optional diagnostics deliberately record touch geometry and selected Shell events locally. Diagnostic logging is off by default.

Troubleshooting

For a useful report, include the laptop/touchpad model, GNOME and Linux versions, session type, Five Pinch version, sensitivity, protection states, and the exact reproduction steps. Open an issue. Remove secrets and personal information from logs before sharing.

Updates & rollback

With the repository configured, ordinary system upgrades include Five Pinch. To update only this package:

sudo apt update
sudo apt install --only-upgrade five-pinch

Log out and back in after upgrading. Your gesture choices are preserved. Opening preferences does not reset them.

Before an experiment, you can save your settings:

dconf dump /org/gnome/shell/extensions/five-pinch/ > five-pinch-settings.dconf

To restore that file, run dconf load /org/gnome/shell/extensions/five-pinch/ < five-pinch-settings.dconf as your own user, without sudo.

For a package rollback, list the available versions and choose one that remains in the repository:

apt-cache policy five-pinch
sudo apt install --allow-downgrades five-pinch=0.6.1

Version 0.6.1 is retained as an older fallback; it does not contain the rinertia fix or simplified interface. A sensitivity change or protection toggle may be enough without downgrading. If necessary, use sudo apt-mark hold five-pinch to keep the chosen version, and sudo apt-mark unhold five-pinch to resume updates. Log out/back in after a downgrade.

Disable or uninstall

To pause gestures, turn off Enable gestures. To stop the extension, disable Five Pinch in GNOME's extension controls. The supervised reader stops with it.

Full removal

Run the first command as your own desktop user, without sudo, while Five Pinch is still installed:

five-pinch-reset
sudo apt purge five-pinch
sudo apt update

five-pinch-reset disables the extension, clears only its own user settings, and removes only its own UUID from GNOME's enabled/disabled extension lists. Package removal also attempts cleanup for reachable user sessions.

apt purge removes package-owned files, including the udev rule, launcher and icon. It also removes the optional Five Pinch APT source, key and pinning files. Ordinary apt remove leaves these repository files available for reinstallation.

On shared machines, each user should run the reset in their own session before removal. Root does not edit logged-out users' personal settings databases. Intentional backups and diagnostic recordings are retained, and a separate manual installation must be removed separately. No drivers or rinertia configuration need restoring because Five Pinch did not change them.

Contribute & inspect the source

Five Pinch is MIT-licensed. Hardware reports, reproducible bug reports, documentation improvements, and code contributions are welcome. There is no device allowlist to ask us to unlock.

Application source · Contribution guide · Hardware reports · Development notes

The release passed 59 Python tests, protocol checks, 31 pinch-tail checks, 38 rinertia checks and 28 mocked Shell checks. The native settings window was rendered with isolated preferences and verified not to change stored values on opening. Automated checks and one-device feedback do not establish universal compatibility.

For tools and agents, this page is also available as a plain-text reference. The application source, release notes and versioned behavior remain the authority when documentation needs updating.