Registry / infi-systray

infi-systray

JSON →
library0.1.12.1pypypi✓ verified 21d ago

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.

pip install infi.systray
INSTALL
IMPORT
SIG · INFI-SYSTRAY
I
infi-systray
pythonv0.1.12.1
Install
2.0s avg
Import
Disk
19MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.12.1 · 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.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.0s · import 0.000s · 18MB
19MB installed
● package 19MB
Code
Verified usage

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

SysTrayIcon
from infi.systray import SysTrayIcon
from infi.systray import SysTrayIcon

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.

import os import sys from infi.systray import SysTrayIcon # This quickstart is designed for Windows environments ONLY, # as infi.systray relies on Windows API calls. # Define menu options and callbacks def on_hello(systray_instance): print("Hello menu item clicked!") def on_goodbye(systray_instance): print("Goodbye menu item clicked!") def on_quit_callback(systray_instance): print("Exiting application from tray icon...") # It's crucial to force exit because systray.start() is blocking. os._exit(0) # Terminate the process # Define the menu structure: (MenuItemText, IconPathForMenuItem, CallbackFunction) menu_options = ( ("Hello", None, on_hello), ("Goodbye", None, on_goodbye), ) # Specify an icon. For a runnable example on Windows without external files, # we can use a system-provided icon from a DLL. 'shell32.dll,1' often points # to a generic application icon. # NOTE: This path is Windows-specific. icon_source = r"C:\Windows\System32\shell32.dll,1" print("Starting infi.systray application...") print("Look for an icon in your Windows system tray (usually bottom-right).") print("Right-click the icon to see the menu. Select 'Quit' to terminate.") # Create the SysTrayIcon instance systray = SysTrayIcon( icon_source, "My infi.systray App", # Text displayed when hovering over the icon menu_options, on_quit=on_quit_callback, default_menu_index=0 # Double-click action (e.g., triggers first menu item) ) # Start the system tray icon. This call blocks the current thread until the # on_quit_callback is triggered and calls os._exit(0). systray.start() print("Application has stopped.") # This line is generally not reached due to os._exit(0)
Debug
Known issues
gotchainfi.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.
fix
Ensure your application is targeting Windows environments or use platform-specific checks to conditionally enable/disable functionality.
affects: All versions
gotchaThe `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.
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.
affects: All versions
gotchaThe `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.
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.
affects: All versions
Upgrade
Version history
0.1.12.1latest on PyPI · released Jan 11, 2025
Audit
Dependencies
infi.osrequiredInternal dependency for operating system abstractions.
pywin32requiredRequired for Windows API interactions to manage the system tray icon.
Agent activity
24 hits · last 30 days
node
22
Amazon
1
Resources
infi-systray — pip install infi-systray · libregistry