GNOME Custom Keyboard Shortcuts for Shell Scripts

The GNOME desktop environment allows users to execute arbitrary shell scripts via custom keybindings using either the graphical Settings application or the command-line gsettings tool. Under the hood, these shortcuts are managed by GNOME Shell and the GNOME Settings Daemon via dconf, which monitors input events and spawns specified commands in non-interactive, non-login user sessions when designated key combinations are triggered.

The Graphical Interface Configuration

Users can configure custom bindings directly through GNOME Settings:

  1. Open Settings and navigate to Keyboard.
  2. Select View and Customize Shortcuts under the Keyboard Shortcuts section.
  3. Scroll to the bottom and select Custom Shortcuts.
  4. Click Add Shortcut (or the + button).
  5. Provide a descriptive Name, enter the absolute path to the script in the Command field, and define the Shortcut combination.

Script Execution and Environment Requirements

When a shortcut is activated, GNOME executes the defined command directly via GLib's process spawning mechanisms (g_spawn_async), rather than within an interactive terminal shell. Because of this architecture, several requirements must be met:

  • Executable Permissions: The target script must have executable permissions set via chmod +x /path/to/script.sh.
  • Shebang Line: The script must begin with a valid shebang (such as #!/bin/bash or #!/usr/bin/env python3) to tell the kernel which interpreter to use.
  • Absolute Paths: GNOME shortcuts run in an environment that may not inherit user-specific $PATH modifications defined in .bashrc or .zshrc. All commands and file references inside the script should use absolute paths.
  • Terminal Emulation: Scripts that require user interaction, standard input, or console output must be invoked through a terminal emulator command (for example: gnome-terminal -- /path/to/script.sh).
  • Desktop Notifications: For headless scripts, visual feedback should be implemented using tools like notify-send or zenity to communicate status to the user.

Backend Architecture and Command-Line Management

GNOME stores and processes custom shortcuts through dconf under the schema org.gnome.settings-daemon.plugins.media-keys.

To create or modify shortcuts programmatically, you define custom keybinding paths:

# Define a unique path for the new shortcut
KEY_PATH="/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/"

# Register the new path in the list of active custom keybindings
gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings \
  "$(gsettings get org.gnome.settings-daemon.plugins.media-keys custom-keybindings | sed -e "s@]$@, '$KEY_PATH']@" -e "s@\\[, @\\[@")"

# Set the name, command, and binding
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:$KEY_PATH name "My Custom Script"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:$KEY_PATH command "/home/user/scripts/run.sh"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:$KEY_PATH binding "<Super><Alt>t"

The GNOME Settings Daemon continuously monitors these configuration keys. Changes made via gsettings or the graphical interface are picked up instantly without requiring a desktop session restart.