Toshy: Mac keyboard shortcuts on Linux, built on a keymapper and a pile of per desktop fixes

A niche utility for people who move between macOS and Linux

The project description says it plainly. Toshy is a keymapper config to make Linux keyboard shortcuts work like a Mac, and more, and it is described as a Kinto alternative.

The audience is stated without hedging in the readme. Toshy is a pretty unique utility for a very niche audience of Mac users who also use Linux, or Linux users who switch between macOS and Linux a lot and prefer the Mac-style keyboard shortcuts. The readme adds that it is difficult for anyone to even think to look for something like Toshy, or Kinto, the original seed project that Toshy was based on.

That is a narrow audience, and the project is candid about why it exists as a GitHub repository rather than a package. The readme says the author spent time making release announcements on Linux related Reddit forums where it seemed most relevant, and that the Reddit account was permanently banned in early January 2025 for no reason that was provided, and that everything posted there is now gone or hidden from Reddit and search engines, and that there was no response to the appeal form. So the distribution problem for a niche utility is itself part of the story, and the readme asks for suggestions of other places where such announcements would be appropriate.

The project describes itself as pretty unique, and the readme is self aware about its length. The first line of the readme is a quote, the Toshy readme is like a phd thesis paper, attributed to a Reddit commenter, and the author answers Yes. Yes, it is. So here are some...

That is a fair description of what follows, and it tells you how to read the project. This is a readme that functions as the manual, the changelog and the support page at once, and that is a deliberate choice rather than a documentation failure.

The readme is the changelog, and the dates are the useful part

The bulk of the readme is a dated list of updates, and reading it in order tells you both what the tool does and what it is still fighting.

The most recent entries are the clearest. On 2026-07-31, support for Alpine Linux was added. On 2026-07-30, functional NixOS support was added, which is not yet applicable to SteamOS or Steam Deck devices. On 2026-06-20, full symbolic output correction was added, so that macro text comes out correctly on other Latin-character non-US keyboard layouts, building on the previous update that allowed shortcuts to operate from the correct physical position and output shortcuts to be corrected for the layout.

The 2026-06-15 entry is the densest. It covers basic non-US keyboard layout correction capability, off by default and working in most common desktop environments, optional bare Meta or Super tap passthru on the Option or Cmd positions, also off by default, Alt_Gr on PC laptop context menu keys which is on by default and controlled by an overlay flag, Level3 Shift from the left-side Option position which is enabled by default, hardware quirk handling for the T2 Mac Touch Bar Fn key in the keymapper, and full touchpad support in the suspend and resume logic, also in the keymapper.

Reading that list, the pattern is clear. Toshy is not a static keymap. It is a set of corrections layered on top of a keymapper, and each correction is tied to a specific desktop environment, a specific keyboard layout, or a specific piece of hardware. The 2026-03-13 entry, adding support for NebiOS, an Ubuntu based distro with a Wayfire based Mac-like desktop environment, is a good example of the shape of the work.

The older entries show the same pattern in reverse, since each one is a bug fixed on one desktop. The 2025-06-13 entry describes a significant defect in the window context provider KWin script component for Plasma Wayland, which had always had trouble seeing window title changes, such as what happens in apps with a tabbed UI, browsers, file managers, terminals and code editors. The fix was to follow the window title changes via the captionChanged() signal from the KWin API, which now allows the window title to be added to app class conditionals in the config file, to invoke custom remaps or actions on specific tabs or sub-dialogs with wonky titles.

That single entry explains more about Toshy's architecture than any feature list could.

A KWin script, a D-Bus service and a wlroots service, one per desktop

The repository layout is the architecture.

There is a kwin-script/ directory, a kwin-dbus-service/ directory, a wlroots-dbus-service/ directory, a wlroots-dev/ directory, a cosmic-dbus-service/ directory, a cinnamon-extension/ directory, and a toshy_gui/ directory, a toshy_tray.py and a toshy_layout_selector.py at the top level, alongside toshy_common/, the default-toshy-config/ directory, the scripts/ directory, and setup_toshy.py.

The pattern is the point. Toshy does not implement one window context provider that works everywhere. It implements one per desktop environment family, because each compositor exposes a different way to learn which window has focus and what its title is.

The KWin script and service cover KDE Plasma, on both X11 and Wayland, with the KWin script doing the title tracking through the KWin API. The wlroots D-Bus service covers the compositors built on wlroots, which the changelog names as labwc, sway, Hyprland, niri, wayfire and river, verified on Tumbleweed, with the kwin_wayland session option still untested. The cosmic-dbus-service/ directory is for the COSMIC desktop, whose support was fixed in October 2024 to work with COSMIC alpha 2 or later, unless they change the relevant Wayland protocol again. The cinnamon-extension/ directory is for Cinnamon, and the 2025-01-18 entry records that the bulk of the available LXQt Wayland session options seem to work, including labwc, sway, Hyprland, niri, wayfire and river.

The 2025-03-02 entry adds another dimension. The solution for working with Synergy as a server or host network KVM switch system was expanded to support Deskflow, Input Leap and Barrier, and it requires a working log file for the KVM switch app in all cases. Client systems are ignored, because input cannot be detected by the keymapper, so no remaps would ever be performed on incoming input from the server system, but the keymapper still operates on a local input device on the client.

That is the whole difficulty of this project in one paragraph. A keymap that works on one compositor does not work on another, and the project is the accumulated set of patches that make it work on more of them.

Installing it, and what the installer actually does to your machine

The readme links two install routes and does not print the commands inline. There is a wiki page for installing Toshy with a single command, and there is a route by downloading the zip from the releases, and the readme's own table of contents lists both.

The requirements.txt file is where the substance of the install shows, and its header is unusually explicit. It warns that this is just a sample requirements.txt file for Toshy and that it is not actually meant to be used manually. The main purpose of making the file is for GitHub to be able to show dependencies. Native package installs are used to provide additional Python modules not named here, for supporting the Python-based keymapper that Toshy installs and works with, and prep build and compile dependencies for some of these pip packages. The setup_toshy.py script handles native package installs and all these pip package installs automatically, and it also installs all pip packages in a venv Python virtual environment, to be more compatible with managed Python environments where pip usage is restricted.

The package list itself explains the shape of the project. There are the base tools, pip, wheel, setuptools and pillow, then pygobject with a version pin to 3.44.1 or earlier to ensure compatibility with RHEL 8.x and its clones and CentOS Stream 8 and CentOS 7, because pygobject 3.51.0 or newer needs GLib 2.80, and the setup script tests for the GLib version and available girepository 2.0 packages.

Then the application dependencies: lockfile, dbus-python, systemd-python, tk, sv_ttk, watchdog and psutil, and xkbcommon with a pin to less than v1.1 on the advice of the repository maintainer or owner, because version 1.5 of xkbcommon introduced breaking API changes.

Two things stand out for an evaluator. First, the xkbcommon pin means the tool is pinned below a version that introduced breaking changes, which is a real constraint on a system with a newer xkbcommon. Second, the whole thing runs in a virtual environment inside a system Python, which is what makes it survivable on a managed distribution. The file is also named DO_NOT_USE_requirements.txt at the repository root, alongside the real requirements.txt, which is a small but clear warning.

Distro support, one entry at a time

The changelog is a record of a project that adds operating systems one at a time, and each addition comes with a caveat that tells you how tested it is.

On 2026-02-02, official support for installing on Gentoo Linux was added, with a note that maybe Calculate Linux and Redcore Linux work too, but only plain Gentoo is tested. On 2026-01, a user implemented support for AerynOS, formerly known as Serpent OS. On 2025-06-15, support for Mageia was added, similar to OpenMandriva and descended from Mandrake and Mandriva distros. On 2025-05-03, support for ALT Linux was added, with a prerequisite that is unusual enough to be worth repeating: install the python3-modules-sqlite3 package, or the setup script will fail immediately with a ModuleNotFoundError, since sqlite3 is normally part of the standard Python library, but ALT seems to keep some of the standard modules in separate packages.

The Chimera entries show the other kind of caveat. On 2025-03-13, support for Chimera Linux, an independent distro with BSD userland utilities, was added, and the GUI preferences app will not work until someone adds a Python Tkinter package to Chimera, because the current maintainer of other Python packages in Chimera was not interested. A second entry the same day notes that Chimera support required adapting the setup script to use doas or run0 if sudo is not available to the user, so that is no longer an impediment to installing Toshy.

The NixOS entry is the same shape. Functional NixOS support was added on 2026-07-30, and the flake.nix and nix/ directories are in the repository, but it is not yet applicable to SteamOS or Steam Deck devices.

Read together, these entries describe a project whose install path is genuinely distribution specific, and whose compatibility is a function of how much work a given distro's packaging has caused. That is a different proposition from a keymapper that installs with one command everywhere, and it is the reason the readme is as long as it is.

The features that are not keymaps, like multi-tap and suspend and resume

Two features in the changelog show that Toshy has moved past simple key substitution.

The first is multi-tap. On 2025-07-01, experimental support was added for a fully asyncio implementation of multi-tap functionality, where a key or combo does different things based on how many times it is tapped within the time limit, 25 milliseconds by default. It does not affect other remaps that are not marked as multi-tap.

A double-tap-to-switch-app pattern is the obvious use, and it is also the obvious way to break a desktop environment if the implementation is wrong. Doing it in asyncio, in a layer that has to sit between the input device and the compositor, is a real engineering decision rather than a configuration option, and the word experimental in the changelog should be taken literally.

The second is the suspend and resume handling. The 2026-06-15 entry lists full touchpad support in the suspend and resume logic, in the keymapper, alongside the T2 Mac Touch Bar Fn key hardware quirk handling. A keymapper that survives a laptop suspend is not a trivial requirement, because the input device can be re-enumerated on resume with a different identifier, and anything that cached the old one is now remapping nothing.

The 2025-07-10 entry describes the other kind of change. Substantial refactoring of multiple internal components has taken place, with very little obvious external sign of the changes, and the ask is to submit issues if you run into problems. That is a maintainer telling you that a refactor landed, and that the regression reports are the way to find out whether it worked.

Together these three entries describe what Toshy actually is. It is not a keymap file. It is a low level input remapping layer, written in Python, that has to be correct at the level of device enumeration, event timing and compositor integration, and the keymap is the visible part of it.

Editorial conclusion

Toshy fits a Mac user on Linux, or a Linux user who moves between macOS and Linux, and who wants Command-Tab, Command-Space and the other macOS shortcuts to work in every application rather than only in the ones a keymapper happens to support. It does not fit a Linux user who is happy with their own shortcuts, because the setup touches the session, the display server and the input stack. Check three things before you install it. Check the current status, which the readme labels Stable Beta and pairs with a dated list of changes, so you can see whether the desktop you use was fixed recently. Check that the distribution is on the tested list, because the changelog shows support being added one distro at a time, and the Gentoo, Alpine and NixOS entries each arrived with a caveat. And check whether the shortcut you want is a remap or a per application conditional, because the KWin script work in 2025 shows that some things are handled by a window context provider, and those behave differently across desktops. The last push was on 2026-10-13, the newest release listed is Toshy v26.08.0 from 2026-08-06, and the license is GPL-3.0.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. RedBearAK/Toshy on GitHub
5. Releases