Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

System wide hotkeys

Project Description

System Hotkey

Multi platform system wide hotkeys for python 3,

Currently no mac or python2 support :(


the old

pip3 install system_hotkey

should do the trick


install pywin32


For x11 you should use xcffib (bsd license),

If for some reason you have to use the python xlib bindings (gpl license), a few fixes need be added first. See here


Input Keysyms

System hotkeys uses the keysym names from xlib for everything besides modifiers.(although case insensitive) grep for vk_codes for a list of available chars. If you are unable to bind to a certain key please let us know.

You can bind directly to symbols such as [“’,. etc Numpad keys can be binded by prefixing with kp_.

Supported modifiers include:

  • control
  • shift
  • super (windows key)
  • alt

InvalidKeyError will be raised if a key was not understood

from system_hotkey import SystemHotkey
hk = SystemHotkeys()
hk.register(('control', 'shift', 'h'), callback=lambda:print("Easy!"))

A SystemRegisterError will be raised if a hotkey is already in use.

To unregister a hotkey

hk.unregister(('control', 'shift', 'h'))

A KeyError will be raised if the combination is not already grabbed.

A UnregisterError will be raised if unregistering failed for any other reason.

If you want you can pass in a custom consumer:

def some_func(self, event, hotkey, args):

hk = SystemHotkeys(consumer=some_func)
hk.register(hotkey, arg1, arg2, arg3)

So you have a master function that receives all hotkey presses and can delegate as desired.

Note Modifier keys are independent of order i.e control + alt + del is the same as alt + control + del


  • Support for up to 3 modifiers and a key


  • I have only mapped most common keys, i have not experimented with Unicode/Japanese characters etc. It’s only a matter of mapping a name to the keysym on Linux and virtual key code on windows.
  • binding to kp_left (key pad left) will also bind to kp_4, there is a flag (unite_kp) to toggle this behaviour but it is experimental

To be done

Mac support

eta > 8 months

Version Release Notes


  • Documented the fact that xlib shouldn’t really be used


  • Fixed a linux bug where spurious events got passed through


  • calls to the unregister and register are now thread safe
  • kp keys work properly
  • kp_unite option


  • Bug fix on linux where pressing numlock would crash us..


  • Custom args can now be passed to a custom consumer

Authors and Contributors

Timothy Eichler

Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node

History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
system_hotkey-1.0.3-py3-none-any.whl (31.6 kB) Copy SHA256 Checksum SHA256 3.5 Wheel Dec 7, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting