{"id":4577,"library":"infi-systray","title":"infi.systray","description":"infi.systray is a Python library that provides an easy way to create a system tray icon for Windows applications. It allows adding custom menus and actions, handling clicks, and managing the icon's lifecycle. Current version is 0.1.12.1, with releases occurring infrequently for maintenance or minor updates.","status":"active","version":"0.1.12.1","language":"en","source_language":"en","source_url":"https://github.com/Infinidat/infi.systray","tags":["windows","gui","systray","tray-icon"],"install":[{"cmd":"pip install infi.systray","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Internal dependency for operating system abstractions.","package":"infi.os","optional":false},{"reason":"Required for Windows API interactions to manage the system tray icon.","package":"pywin32","optional":false}],"imports":[{"symbol":"SysTrayIcon","correct":"from infi.systray import SysTrayIcon"}],"quickstart":{"code":"import os\nimport sys\nfrom infi.systray import SysTrayIcon\n\n# This quickstart is designed for Windows environments ONLY,\n# as infi.systray relies on Windows API calls.\n\n# Define menu options and callbacks\ndef on_hello(systray_instance):\n    print(\"Hello menu item clicked!\")\n\ndef on_goodbye(systray_instance):\n    print(\"Goodbye menu item clicked!\")\n\ndef on_quit_callback(systray_instance):\n    print(\"Exiting application from tray icon...\")\n    # It's crucial to force exit because systray.start() is blocking.\n    os._exit(0) # Terminate the process\n\n# Define the menu structure: (MenuItemText, IconPathForMenuItem, CallbackFunction)\nmenu_options = (\n    (\"Hello\", None, on_hello),\n    (\"Goodbye\", None, on_goodbye),\n)\n\n# Specify an icon. For a runnable example on Windows without external files,\n# we can use a system-provided icon from a DLL. 'shell32.dll,1' often points\n# to a generic application icon.\n# NOTE: This path is Windows-specific.\nicon_source = r\"C:\\Windows\\System32\\shell32.dll,1\"\n\nprint(\"Starting infi.systray application...\")\nprint(\"Look for an icon in your Windows system tray (usually bottom-right).\")\nprint(\"Right-click the icon to see the menu. Select 'Quit' to terminate.\")\n\n# Create the SysTrayIcon instance\nsystray = SysTrayIcon(\n    icon_source,\n    \"My infi.systray App\",  # Text displayed when hovering over the icon\n    menu_options,\n    on_quit=on_quit_callback,\n    default_menu_index=0 # Double-click action (e.g., triggers first menu item)\n)\n\n# Start the system tray icon. This call blocks the current thread until the\n# on_quit_callback is triggered and calls os._exit(0).\nsystray.start()\n\nprint(\"Application has stopped.\") # This line is generally not reached due to os._exit(0)","lang":"python","description":"This example demonstrates how to create a basic system tray icon with a menu on Windows. It uses a system icon from `shell32.dll` to ensure the example is runnable without requiring a separate `.ico` file. Right-click the tray icon to see the 'Hello' and 'Goodbye' options, and 'Quit' to terminate the application. Note that `infi.systray` is Windows-specific and this example will only function on Windows."},"warnings":[{"fix":"Ensure your application is targeting Windows environments or use platform-specific checks to conditionally enable/disable functionality.","message":"infi.systray is strictly a Windows-only library. It relies on Windows API calls and will not function on macOS, Linux, or any other operating system.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run `systray.start()` in a dedicated `threading.Thread` to keep your main application thread free for other operations. Remember to handle thread shutdown gracefully.","message":"The `SysTrayIcon.start()` method is blocking. It will run the message loop on the current thread, preventing other code from executing until the tray icon is explicitly quit. For applications requiring responsiveness or other concurrent tasks, `SysTrayIcon` must be run in a separate thread.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the icon path is correct and accessible. For bundled applications, ensure the icon is included in the distribution and its path is resolved correctly at runtime.","message":"The `SysTrayIcon` constructor requires a valid path to an icon file (.ico) or a resource identifier (e.g., `C:\\Windows\\System32\\shell32.dll,1`). Providing an invalid path or a non-existent file will result in an error or a missing icon.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}