How to Set Up the GMK87 Keyboard on macOS and Linux
The Zuoya GMK87 (also sold as the GMK87) ships with a built-in LCD screen, RGB lighting, and a real-time clock. However, the official configuration software only works on Windows. If you use macOS or Linux, you have no way to upload images to the screen, sync the clock, or fine-tune lighting with the stock tools.
The GMK87 Configurator is a free, open-source alternative that works on macOS, Linux, and Windows. It is currently the only way to configure the GMK87 keyboard screen and display on macOS and Linux.
What you can do with the GMK87 Configurator
- Upload custom images to the keyboard's built-in LCD screen
- Sync the keyboard's clock to your computer's time
- Configure RGB lighting effects, brightness, speed, and color
- Works via a desktop app (recommended) or command-line interface
On this page
Prerequisites
- A Zuoya GMK87 keyboard (the 87-key model with the built-in LCD screen).
- A USB connection. The configurator communicates over USB HID. Bluetooth will not work for configuration.
- For the desktop app: No additional dependencies needed. Just download and run.
- For the CLI: Node.js 18 or later.
Setup on macOS
macOS is the most straightforward platform. No drivers or special permissions are required -- HID access works out of the box.
Download the GMK87 Configurator
Go to the latest release page and download the .dmg file for macOS.
Choose the arm64 build for Apple Silicon Macs (M1/M2/M3/M4) or the x64 build for Intel Macs.
Install the app
Open the .dmg file and drag the GMK87 Configurator into your Applications folder.
On first launch, macOS may show a security prompt. Go to System Settings > Privacy & Security and click "Open Anyway".
Connect your keyboard via USB
Plug your GMK87 into your Mac using the USB cable. Make sure the keyboard is powered on. The configurator will automatically detect it.
Launch the app and configure
Open the GMK87 Configurator from your Applications folder. You can now sync the clock, upload images, and configure lighting.
Setup on Linux
Linux requires one extra step: setting up a udev rule so the configurator can access the keyboard's HID interface without root privileges.
Download the GMK87 Configurator
Go to the latest release page and download the .AppImage or .deb file for Linux.
Create a udev rule for HID access
Without this rule, only root can communicate with the keyboard over HID. Create a udev rule file:
sudo nano /etc/udev/rules.d/99-gmk87.rulesAdd the following line (the GMK87 uses vendor ID 0x05ac and product ID 0x024f):
KERNEL=="hidraw*", ATTRS{idVendor}=="05ac", ATTRS{idProduct}=="024f", MODE="0666"Then reload udev rules and re-plug the keyboard:
sudo udevadm control --reload-rules
sudo udevadm triggerAlternatively, unplug and replug the keyboard after reloading the rules.
Make the AppImage executable (if using AppImage)
chmod +x GMK87-Configurator-*.AppImageConnect your keyboard and launch
Plug in your GMK87 via USB and run the app. You can now sync the clock, upload images, and configure lighting.
Setup on Windows
While the official Zuoya software works on Windows, you may still prefer the GMK87 Configurator for its simpler interface or to avoid the stock Chinese-language software.
Download and install
Go to the latest release page and download the .exe installer. Run it and follow the prompts.
Connect your keyboard and launch
Plug in the GMK87 via USB and open the GMK87 Configurator from the Start Menu. No special drivers or permissions needed.
Initial Configuration (All Platforms)
Once the app is installed and your keyboard is connected, here is what you should do first:
Sync the clock
The GMK87 has a built-in clock displayed on its screen, but it does not sync automatically. Every time you want to update the time, you need to sync it manually.
In the app, click the Time Sync button. The keyboard's clock will update to your computer's current time within a second.
Upload an image to the screen
The keyboard's LCD screen can display a custom image. In the app, use the Image Upload feature to select any image file. The configurator will automatically resize and convert it for the keyboard's display.
Supported formats: PNG, JPG, BMP, and other common image formats. The image will be resized to fit the keyboard's screen resolution.
Configure lighting (optional)
Use the Lighting section to adjust RGB effects, brightness, and animation speed. Changes are applied immediately and saved to the keyboard.
Using the CLI Instead of the App
If you prefer the command line, or need to script keyboard configuration, you can use the GMK87 CLI directly. This requires Node.js 18+.
Install the CLI
npm install -g gmk87Or run it without installing using npx:
npx gmk87Sync the clock
npx gmk87 timesyncUpload an image to the screen
npx gmk87 upload path/to/your-image.pngConfigure lighting
npx gmk87 lightsLinux CLI users
You still need the udev rule described in the Linux setup section above, even when using the CLI. Without it, you would need to run commands with sudo.
Troubleshooting
"Keyboard not found" or "No device detected"
- Make sure the keyboard is connected via USB, not Bluetooth.
- Try a different USB port or cable.
- On Linux, verify the udev rule is in place and you have reloaded rules (
sudo udevadm control --reload-rules). - On macOS, check that no other application (like the official Zuoya software in a VM) is holding the HID device open.
macOS "app is damaged" or security warning
Go to System Settings > Privacy & Security, scroll down, and click "Open Anyway" next to the GMK87 Configurator entry. This only needs to be done once.
Image upload seems stuck or fails
- Unplug the keyboard, wait a few seconds, and plug it back in.
- Make sure no other program is communicating with the keyboard at the same time.
- Try a smaller image file first to rule out file format issues.
Clock resets after unplugging
The GMK87 has a small internal battery to keep the clock running. If the clock resets frequently, the internal battery may be low. Re-syncing the time after each USB connection is the simplest workaround.