pystray Package Documentation

This library allows you to create a system tray icon.

It allows specifying an icon, a title and a callback for when the icon is activated. The icon and title can be changed after the icon has been created, and the visibility of the icon can be toggled.

Creating a system tray icon

In order to create a system tray icon, the class pystray.Icon is used:

import pystray

icon = pystray.Icon('test name')

In order for the icon to be displayed, you must provide an icon. This icon must be specified as a PIL.Image.Image:

from PIL import Image, ImageDraw

# Generate an image
image = Image.new('RGB', (width, height), color1)
dc = ImageDraw.Draw(image)
dc.rectangle((width // 2, 0, width, height // 2), fill=color2)
dc.rectangle((0, height // 2, width // 2, height), fill=color2)

icon.icon = image

To ensure that your application runs on all platforms, you must then run the following code to show the icon:

def setup(icon):
    icon.visible = True

icon.run(setup)

The call to pystray.Icon.run() is blocking, and it must be performed from the main thread of the application. The reason for this is that the system tray icon implementation for OSX must be run from this thread, and it requires the application runloop to be running. pystray.Icon.run() will start the runloop.

The code in setup() will be run in a separate thread once the system tray icon is ready. The icon does not wait for it to complete, so you may put any code that would follow the call to pystray.Icon.run() in it.

The call to pystray.Icon.run() will not complete until stop() is called.

Getting input from the system tray icon

In order to receive notifications about user interaction with the icon, a popup menu can be added with the menu constructor argument.

This should be an instance of pystray.Menu, or a tuple that can be passed to the pystray.Menu constructor. Please see the reference for more information about the format.

It will be displayed when the right-hand button has been pressed on the icon on Windows and GTK+, and when the icon has been clicked on OSX. Menus are not supported on X.

Menus also support a default item. On Windows, GTK+ and X, this item will be activated when the user clicks on the icon using the primary button. On OSX it will be activated if the menu contains no visible entries; it does not have to be visible.

All properties of menu items, except for the callback, can be dynamically calculated by supplying callables instead of values to the menu item constructor. The properties are recalculated every time the icon is clicked or any menu item is activated.

If the dynamic properties change because of an external event, you must ensure that Icon.update_menu is called. This is required since not all supported platforms allow for the menu to be generated when displayed.

Reference

class pystray.Icon(name, icon=None, title=None, menu=None)[source]

A representation of a system tray icon.

The icon is initially hidden. Call show() to show it.

Parameters:
  • name (str) – The name of the icon. This is used by the system to identify the icon.
  • icon – The icon to use. If this is specified, it must be a PIL.Image.Image instance.
  • title (str) – A short title for the icon.
  • menu –

    A menu to use as popup menu. This can be either an instance of Menu or a tuple, which will be interpreted as arguments to the Menu constructor.

    The behaviour of the menu depends on the platform. Only one action is guaranteed to be invokable: the first menu item whose default attribute is set.

    Some platforms allow both menu interaction and a special way of activating the default action, some platform allow only either an invisible menu with a default entry as special action or a full menu with no special way to activate the default item, and some platforms do not support a menu at all.
HAS_DEFAULT_ACTION = True

Whether this particular implementation has a default action that can be invoked in a special way, such as clicking on the icon.

HAS_MENU = True

Whether this particular implementation supports menus.

icon

The current icon.

Setting this to a falsy value will hide the icon. Setting this to an image while the icon is hidden has no effect until the icon is shown.

menu

The menu.

Setting this to a falsy value will disable the menu.

name

The name passed to the constructor.

run(setup=None)[source]

Enters the loop handling events for the icon.

This method is blocking until stop() is called. It must be called from the main thread.

Parameters:setup (callable) – An optional callback to execute in a separate thread once the loop has started. It is passed the icon as its sole argument.
stop()[source]

Stops the loop handling events for the icon.

title

The current icon title.

update_menu()[source]

Updates the menu.

If the properties of the menu descriptor are dynamic, that is, any are defined by callables and not constants, and the return values of these callables change by actions other than the menu item activation callbacks, calling this function is required to keep the menu in sync.

This is required since not all supported platforms allow the menu to be generated when shown.

For simple use cases where menu changes are triggered by interaction with the menu, this method is not necessary.

visible

Whether the icon is currently visible.

Raises:ValueError – if set to True and no icon image has been set