{"id":7609,"library":"pystray","title":"pystray","description":"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.","status":"active","version":"0.19.5","language":"en","source_language":"en","source_url":"https://github.com/moses-palmer/pystray","tags":["GUI","system tray","icon","cross-platform","desktop"],"install":[{"cmd":"pip install pystray pillow","lang":"bash","label":"Install pystray and Pillow"}],"dependencies":[{"reason":"Required for image handling and creating icons.","package":"Pillow","optional":false}],"imports":[{"note":"While `import pystray` is common, importing `Icon` directly is more explicit and generally preferred.","wrong":"import pystray.Icon","symbol":"Icon","correct":"from pystray import Icon"},{"note":"Import `Menu` and `MenuItem` directly for clearer usage when defining menu structures.","wrong":"import pystray.Menu","symbol":"Menu","correct":"from pystray import Menu, MenuItem"},{"note":"Pillow's `Image` module is a dependency and must be imported from `PIL`, not directly.","wrong":"import Image","symbol":"Image","correct":"from PIL import Image, ImageDraw"}],"quickstart":{"code":"import pystray\nfrom PIL import Image, ImageDraw\nimport os\n\ndef create_image(width, height, color1, color2):\n    # Generate a simple image for the icon\n    image = Image.new('RGB', (width, height), color1)\n    dc = ImageDraw.Draw(image)\n    dc.rectangle((width // 2, 0, width, height // 2), fill=color2)\n    dc.rectangle((0, height // 2, width // 2, height), fill=color2)\n    return image\n\ndef quit_action(icon, item):\n    icon.stop()\n\ndef show_message(icon, item):\n    print(\"Hello from the tray icon!\")\n\n# Create an image for the icon\nicon_image = create_image(64, 64, 'black', 'white')\n\n# Define the menu\nmenu = (\n    pystray.MenuItem('Say Hello', show_message),\n    pystray.MenuItem('Quit', quit_action)\n)\n\n# Create and run the icon\nicon = pystray.Icon('my_app_name', icon_image, 'My Awesome App', menu)\n\n# For simple, blocking execution, use icon.run()\n# For integration with other GUI frameworks, consider icon.run_detached() in a separate thread.\n# In this example, we'll use run() for simplicity.\nprint(\"pystray icon is running. Right-click for menu, or click 'Quit' to exit.\")\nicon.run()","lang":"python","description":"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."},"warnings":[{"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.","message":"`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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"Menus are not supported or have limited functionality on certain Linux backends (e.g., Xorg). `Icon.HAS_MENU` can be checked at runtime.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Older versions of pystray might have compatibility issues with newer Pillow versions or Python releases, leading to `RuntimeWarning` or unexpected behavior.","severity":"deprecated","affected_versions":"<0.19.5"},{"fix":"Use `icon.run_detached()` in a separate thread to allow both the tray icon and the GUI framework to run concurrently.","message":"When integrating `pystray` with other GUI frameworks (like Tkinter or PySimpleGUI), `icon.run()` will block the main loop of the other framework.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade Pillow to the latest version (`pip install --upgrade Pillow`). If the issue persists with a very new Python version, consider downgrading Python to a version officially supported by the latest Pillow release.","cause":"The installed version of Pillow is not fully compatible with the current Python version, especially on Windows or very new Python releases.","error":"RuntimeWarning: Pillow X.Y.Z does not support Python 3.NN and does not provide prebuilt Windows binaries."},{"fix":"Ensure `PyGObject` is installed, especially for AppIndicator backend (`pip install pygobject`). If using a virtual environment on Linux, additional system packages (like `libcairo-dev`, `libgirepository1.0-dev`) might be needed for PyGObject to build. On Xorg, menu support is limited or non-existent.","cause":"The current Linux desktop environment or backend might not support menus or requires specific dependencies (e.g., AppIndicator, PyGObject).","error":"My pystray icon appears but the menu doesn't show up or doesn't respond on Linux."},{"fix":"Run the `pystray` icon in a separate thread using `icon.run_detached()`. For example: `import threading; threading.Thread(target=icon.run_detached).start()`.","cause":"`icon.run()` is a blocking call and competes for the main thread with your GUI framework's event loop.","error":"My application freezes when I call `icon.run()` after initializing my Tkinter window."}]}