pystray

What it is and what it does

Pystray is a cross-platform library for creating system tray icons with popup menus. It abstracts away platform differences by selecting the appropriate backend (native Windows APIs, Cocoa on macOS, GTK+/AppIndicator/Xlib on Linux) and presenting a unified Python API. You create an Icon object, optionally define a menu with callbacks, and call run() to display it in the system tray.

The package handles the full lifecycle of tray interaction—icon display, menu rendering, notifications, and event dispatch—while managing platform-specific quirks. It supports nested menus, checkboxes, radio buttons, disabled items, and can run in detached mode to integrate with other event loops.

Use it for:

• Build a background application that lives in the system tray with a menu for quick access to settings or actions
• Add tray icon notifications to a long-running service or daemon on Windows, macOS, or Linux
• Create a cross-platform GUI tool that minimizes to tray instead of closing, using a single codebase
• Integrate tray icon support into an existing application that uses GTK+ or another event loop via detached mode

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Pystray creates a system tray icon with an optional popup menu that works across Windows, macOS, and Linux using platform-specific backends.

Yes, if you need cross-platform tray icon support and can accept that the project is in maintenance mode. The library is stable and widely used, has no known vulnerabilities, and low install friction. The main trade-off is the aging maintenance status—no active feature development, and you may need to verify compatibility with Python versions newer than those listed in classifiers.

Install

pystray on PyPI

pip install pystray

uv add pystray

poetry add pystray

Installing pystray

Before you install

Install friction is low; the package is a pure-Python wheel. Maintenance is aging—the last release was 2023-09-17, though the repository remains active with recent commits and is not archived.

License in practice

Licensed under LGPLv3 (copyleft). Any derivative work or distribution must preserve the license and make source available; static linking or closed-source wrapping is not permitted.

Quickstart

pip install pystray

import pystray

icon = pystray.Icon('test')
icon.run()

Requires a display server (X11, Wayland, Windows, or macOS); will not run headless. Platform-specific dependencies: pyobjc-framework-Quartz on macOS, python-xlib on Linux, and GTK+ or AppIndicator libraries on some Linux distributions.

Verify before relying

• Whether the package works reliably with modern Python versions (3.10+) given classifiers only list up to 3.4
• Current state of GTK+ and AppIndicator backend stability on modern Linux distributions
• Whether notifications work consistently across all supported platforms

Package facts

Evidence: pystray-0.19.5-py2.py3-none-any.whl

Keywords: system tray icon, systray icon

Tags

More Utilities packages