pystray

library0.19.5pypypiunverified

pystray is a Python library that provides cross-platform system tray icon integration. It allows developers to create a system tray icon, define a title, set an image, and attach a popup menu with various actions. The current stable version is 0.19.5, with releases typically occurring as needed for bug fixes and feature enhancements, rather than on a strict schedule.

communication

pip install pystray pillow

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PYSTRAY

pystray

communicationpythonv0.19.5

Install

2.4s avg

Import

—

Disk

37MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.19.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 39.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.4s · import 0.000s · 40MB

37MB installed

● package 37MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Icon

✓ from pystray import Icon

✗ import pystray.Icon

While `import pystray` is common, importing `Icon` directly is more explicit and generally preferred.

✓ from pystray import Menu, MenuItem

✗ import pystray.Menu

Import `Menu` and `MenuItem` directly for clearer usage when defining menu structures.

Image

✓ from PIL import Image, ImageDraw

✗ import Image

Pillow's `Image` module is a dependency and must be imported from `PIL`, not directly.

This quickstart demonstrates how to create a basic system tray icon with a custom image and a context menu. It defines functions for menu actions and runs the icon in a blocking loop. For integration with other GUI frameworks, `run_detached()` or threading should be considered.

import pystray from PIL import Image, ImageDraw import os def create_image(width, height, color1, color2): # Generate a simple image for the icon 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) return image def quit_action(icon, item): icon.stop() def show_message(icon, item): print("Hello from the tray icon!") # Create an image for the icon icon_image = create_image(64, 64, 'black', 'white') # Define the menu menu = ( pystray.MenuItem('Say Hello', show_message), pystray.MenuItem('Quit', quit_action) ) # Create and run the icon icon = pystray.Icon('my_app_name', icon_image, 'My Awesome App', menu) # For simple, blocking execution, use icon.run() # For integration with other GUI frameworks, consider icon.run_detached() in a separate thread. # In this example, we'll use run() for simplicity. print("pystray icon is running. Right-click for menu, or click 'Quit' to exit.") icon.run()

Debug

Known issues

breaking`pystray.Icon.run()` is a blocking call and must be run in the main thread on macOS for the system tray icon to function correctly.

fix

For macOS, always call `icon.run()` from the main thread. If integrating with another GUI framework that requires the main thread, use `icon.run_detached()` in a separate thread.

affects: All versions

gotchaMenus are not supported or have limited functionality on certain Linux backends (e.g., Xorg). `Icon.HAS_MENU` can be checked at runtime.

fix

Check `pystray.Icon.HAS_MENU` property at runtime to determine if menu functionality is available on the current platform and backend. Consider providing alternative interactions for platforms without full menu support.

affects: All versions

deprecatedOlder versions of pystray might have compatibility issues with newer Pillow versions or Python releases, leading to `RuntimeWarning` or unexpected behavior.

fix

Ensure both `pystray` and `Pillow` are updated to their latest stable versions (`pip install --upgrade pystray pillow`). If encountering issues with very new Python versions (e.g., 3.13+), consider using a slightly older Python version (e.g., 3.12) until full compatibility is established.

affects: <0.19.5

gotchaWhen integrating `pystray` with other GUI frameworks (like Tkinter or PySimpleGUI), `icon.run()` will block the main loop of the other framework.

fix

Use `icon.run_detached()` in a separate thread to allow both the tray icon and the GUI framework to run concurrently.

affects: All versions

Upgrade

Version history

0.19.5latest on PyPI · released Sep 17, 2023

Audit

Dependencies

PillowrequiredRequired for image handling and creating icons.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/moses-palmer/pystray ↗

packagehttps://pypi.org/project/pystray/ ↗

homepagehttps://pystray.readthedocs.io ↗