The [Toshy] readme is like a phd thesis paper.
-- No_Sandwich3888 on Reddit

Yes. Yes, it is. So here are some...

... Quick Links!

(See top-right icon here on GitHub for full README table of contents)

• How to Install
• How to Uninstall
• Requirements
• Supported Desktop Environments/Window Managers
• Supported Linux Distros
• Frequently Asked Questions (FAQ)
• Sponsor/Donate

◊

Help others find out about Toshy

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. It's difficult for anyone to even think to look for something like Toshy, or Kinto (the original seed project that Toshy was based on). If you want anyone else to know about Toshy, you'll have to make a post or comment about it somewhere, on your own.

I spent time making some release announcements on various Linux-related Reddit forums over the past couple of years, where it seemed to be most relevant. But my Reddit account was suddenly "permanently banned" in early January 2025, for no reason that has been provided to me, either by email or in my Reddit messages inbox. So everything I ever posted there is now gone, or at least hidden from Reddit and search engines. I don't really have any interest in ever posting on that site again, even if the account could be unbanned. Before you ask, there was no response to the appeal form.

I don't really know many other places where it might be considered appropriate to make announcements about the releases/updates of an open source project like this, where it would get the attention of the type of Mac/Linux users who would find it interesting or useful. If you have suggestions, open a (question) issue here.

◊

Current status: Stable Beta (Please Read)

2026-03-13: Added support for NebiOS, an Ubuntu-based distro with a Wayfire-based Mac-like desktop environment (NebiDE).

2026-02-02 UPDATE: Finally added official support for installing on Gentoo Linux. Maybe also Calculate Linux and Redcore Linux, but only plain Gentoo is tested. Thanks to user @sazz who proved that it was possible to get Toshy running on Gentoo in issue 775.

2026-01 UPDATE: Toshy user @armerpunkt implemented support for AerynOS (formerly known as Serpent OS). See PR 771.

2025-07-10 UPDATE: Substantial refactoring of multiple internal components has taken place. There should be very little obvious external sign of the changes, but submit issues if you run into problems.

2025-07-01 UPDATE: Added experimental support for fully asyncio implementation of multi-tap functionality. Have a key or combo do different things based on how many times it's tapped within the time limit (25ms default). Does not affect other remaps that aren't marked as multi-tap.

2025-06-15 UPDATE: Added support for Mageia (similar to OpenMandriva and descended from Mandrake/Mandriva distros).

2025-06-13 UPDATE: The window context provider KWin script component (for Plasma Wayland) has always had a significant defect in seeing window title changes, such as what happens in apps with a tabbed UI (browsers, file managers, terminals, code editors, etc.). That KWin script has been updated to follow the window title changes via the captionChanged() signal, from the KWin API. Now the window title (name) can 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. And it will work in Plasma just as reliably as in all other Wayland environments (and X11).

2025-05-03 UPDATE: Added support for ALT Linux, another independent distro type. Required prerequisite: Install the 'python3-modules-sqlite3' package, or the setup script will fail immediately with a ModuleNotFoundError. This is unusual, since sqlite3 is normally part of the standard Python library, but ALT seems to keep some of the standard modules in separate packages.

2025-03-13 UPDATE: The Chimera support required adapting the setup script to use doas or run0 if sudo is not available to the user. So this is no longer an impediment to installing Toshy.

2025-03-13 UPDATE: Added support for Chimera Linux, an independent distro with BSD userland utilities. GUI preferences app will not work until someone adds a Python Tkinter package to Chimera. The current maintainer of other Python packages in Chimera was not interested.

2025-03-02 UPDATE: The solution for working with Synergy as a server/host network KVM switch system was expanded to support Deskflow, Input Leap and Barrier. (Requires 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 will still operate on a local input device on the client.

2025-01-18 UPDATE: Fixed some issues in the wlroots window context method, and verified the bulk of the available LXQt Wayland session options seem to work. That includes labwc, sway, Hyprland, niri, wayfire, and river (tested on Tumbleweed). The kwin_wayland session option is still untested (unavailable on Tumbleweed for now).

2024-11-28 UPDATE: Added support for Pantheon's Wayland session in elementary OS 8.

2024-10-03 UPDATE: Fixed the broken COSMIC desktop environment support to work with COSMIC alpha 2 or later (unless they change the relevant Wayland protocol again).

2024-07-28 UPDATE: Some basic wlroots based Wayland compositor support has been added. See the Wiki article.

2024-07-14 UPDATE: Toshy was recently mentioned favorably in a video on Framework's YouTube channel, about transitioning from macOS to Linux, by Zach Feldman, a lead software engineer on the Marketplace team at Framework. I discovered this quite by accident, watching the video simply because it was in my recommended videos and the title said it was about macOS and Linux, and I've watched several videos from the Framework team. Imagine my surprise when Zach said one of the more important tools that allowed him to use Linux productively after using macOS for many years was Toshy. 😲🤯 Well, I can't be that surprised, since that's exactly why Toshy (and Kinto) were put together. Toshy references start about 2 minutes into the video:

https://www.youtube.com/watch?v=g4aUSRi8QX4

For new updates on the performance advancements, check the dedicated Wiki page.

◊

Main issues you might run into

• KEYBOARD TYPE: The Toshy config file tries to automatically identify the "type" of your keyboard based on some pre-existing lists of keyboard device names, which do not have many entries, and there are thousands of keyboard name variants. So your keyboard may be misidentified, leading to modifier keys in the "wrong" place. BE PREPARED to identify the name of your keyboard device (try toshy-devices in a terminal) and enter it into the custom list (actually a Python "dictionary") in the config file to fix this problem. The custom entry is designed to be retained even if you reinstall later. There is a sub-menu in the tray icon menu intended to allow temporarily bypassing this problem while you find the device name and enter it in your config file. Go to this FAQ entry for more info:

  Keyboard Type Not Correct

• INTERNATIONAL KEYBOARD USERS: The keymapper is evdev-based and has no idea what keyboard layout you are using. It only sees "key codes", not the symbols on the keys. So if it encounters a combo of key codes you've asked it to remap to something else, it will remap it. This is a problem if for instance you're on an AZERTY keyboard where A and Q are swapped, and you think you're pressing Cmd+A but the keymapper thinks you want to remap Cmd+Q to Alt+F4. I'm looking into a way to get the keymapper to use the proper layout, but in the meantime, depending on how different your layout is from the standard US layout, this keymapper may either be unusable or may just need some small tweaks to the key definition file to fix a few key positions. Open an issue if you have this kind of problem.

• DISTRO SUPPORT: Toshy will have issues installing on distros not on the list of supported distros in the Wiki. If you think your distro is closely related to one on the supported list, try the ./setup_toshy.py list-distros command, and then use one of the distro names with the --override-distro option added to the ./setup_toshy.py install command. See the How to Install section.

• STARTUP: Toshy may seem to run at login, but not do any remapping, needing the use of the debugging command toshy-debug in the terminal to troubleshoot. Or, it may just need a restart of the services from the tray icon or with toshy-services-restart. Check the output of toshy-services-log and toshy-services-status first to see if there is an obvious error message that explains the problem. Like not having a compatible GNOME Shell extension installed/enabled to support a Wayland+GNOME session. Other than the Wayland+GNOME situation, I don't really see this much anymore.

• INIT SYSTEMS: On a dual-init distro like MX Linux, if you install Toshy while using SysVinit (default on MX) the installer will avoid installing the systemd