CopyQ macOS Troubleshooting: Invisible GUI and Manual Hotkey Configuration¶
This guide addresses common issues encountered on macOS (specifically Apple Silicon M-series devices) where the CopyQ graphical interface (GUI) does not appear, or global shortcuts (such as F10) need to be reassigned without accessing the GUI.
1. Troubleshooting the Invisible GUI¶
On macOS, CopyQ may run properly in the background while remaining visually hidden for two main reasons:
Off-Screen Window Coordinates: Following resolution changes or disconnecting an external monitor, CopyQ may retain coordinates outside the visible display area.
Menu Bar Notch Obstruction: On MacBook models with a camera notch, macOS automatically conceals excess menu bar icons behind the notch when the tray is full.
Solution: Reset Geometry and Force Display¶
Execute the following commands in the terminal to clear off-screen coordinates and bring the window to the foreground:
copyq config geometry ""
copyq show
If the window still does not surface, toggle its state via CLI:
copyq toggle
2. Manually Changing Hotkeys Using CudaText¶
When a global shortcut (such as F10) is claimed or intercepted by another application, the shortcut can be edited directly in the configuration file using CudaText without opening the CopyQ GUI.
Step 1: Terminate the CopyQ Process¶
CopyQ must be stopped before editing the configuration file to prevent it from overwriting your changes upon termination:
copyq exit
Step 2: Open the Configuration in CudaText¶
On macOS, CopyQ command shortcuts are stored in copyq-commands.ini.
Open the file in CudaText:
cudatext "$HOME/Library/Application Support/copyq/copyq-commands.ini"
Note: If the file does not exist in Application Support, open the XDG fallback location:
cudatext "$HOME/.config/copyq/copyq-commands.ini"
Step 3: Reassign the Shortcut¶
1- In CudaText, press Cmd + F to open the search bar.
2- Search for F10 or GlobalShortcut=F10.
3- Replace F10 with an available shortcut (e.g., F9 or Ctrl+F10 or Meta+F10).
4- Save the file (Cmd + S) and close CudaText (Cmd + Q).
Step 4: Restart CopyQ¶
Start CopyQ again to load the updated shortcut configuration:
open -a CopyQ
The new global shortcut will now be active.
(updated: 8.9.’26 08:01 Tue)