Python GUIs - qsystemtrayicon

QSystemTrayIcon — Adding Menu Items in a Loop — Why dynamically created QActions disappear and how to fix it

2021-01-15T09:00:00+00:00

I'm trying to populate a QSystemTrayIcon context menu using a for loop, but only the last item shows up. What happened to the other entries, and how do I fix it?

If you've ever tried to build a system tray menu dynamically — say, by looping through a list of items — you may have run into a confusing problem: only the last menu item appears. The earlier ones vanish without any error message. Let's look at why this happens and how to solve it.

Here's a minimal example that demonstrates the issue. We have a list of three entries and we loop through them, creating a QAction for each one:

python

from PyQt6.QtWidgets import QApplication, QSystemTrayIcon, QMenu
from PyQt6.QtGui import QAction, QIcon


app = QApplication([])
app.setQuitOnLastWindowClosed(False)

icon = QIcon.fromTheme("application")
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setVisible(True)

menu = QMenu()
entries = ["One", "Two", "Three"]
for entry in entries:
    action = QAction(entry)
    menu.addAction(action)
    action.triggered.connect(app.quit)

tray.setContextMenu(menu)

app.exec()

You'd expect to see three items in the menu — "One", "Two", and "Three" — but only "Three" appears. The first two have vanished.

Why this happens: Python garbage collection

The cause is Python's garbage collector. When you create an object and assign it to a variable, Python keeps that object alive as long as something is referencing it. Once nothing references it anymore, Python is free to delete it.

In the loop above, the variable action is reassigned on every iteration. On the second pass through the loop, action now points to the new QAction("Two"), and the previous QAction("One") no longer has any Python reference. Python garbage-collects it, which also destroys the underlying Qt C++ object — and removes it from the menu.

By the time the loop finishes, only the last QAction survives because action still points to it.

This is a common source of confusion when working with PyQt6 (and PySide6). Qt's C++ side doesn't always take full ownership of objects you pass to it, so Python's garbage collector can sweep them away unexpectedly.

The fix: keep references to your actions

The solution is straightforward — store each QAction somewhere so Python keeps it alive. A simple list works perfectly:

python

from PyQt6.QtWidgets import QApplication, QSystemTrayIcon, QMenu
from PyQt6.QtGui import QAction, QIcon


app = QApplication([])
app.setQuitOnLastWindowClosed(False)

icon = QIcon.fromTheme("application")
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setVisible(True)

menu = QMenu()
entries = ["One", "Two", "Three"]
actions = []
for entry in entries:
    action = QAction(entry)
    menu.addAction(action)
    action.triggered.connect(app.quit)
    actions.append(action)

tray.setContextMenu(menu)

app.exec()

The only change is the actions list. By appending each QAction to this list, we ensure that every action has a live Python reference for the lifetime of the program. Now all three items appear in the menu as expected.

Another approach is to pass a parent to each QAction. When a Qt object has a parent, Qt takes ownership of it and manages its lifetime. This means Python's garbage collector won't destroy it, because the C++ side is keeping it alive:

python

from PyQt6.QtWidgets import QApplication, QSystemTrayIcon, QMenu
from PyQt6.QtGui import QAction, QIcon


app = QApplication([])
app.setQuitOnLastWindowClosed(False)

icon = QIcon.fromTheme("application")
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setVisible(True)

menu = QMenu()
entries = ["One", "Two", "Three"]
for entry in entries:
    action = QAction(entry, menu)  # menu is the parent
    menu.addAction(action)
    action.triggered.connect(app.quit)

tray.setContextMenu(menu)

app.exec()

By passing menu as the second argument to QAction, each action becomes a child of the menu. Qt will keep the action alive as long as the menu exists, so there's no need for a separate list.

Both approaches work well. Using a parent is often the cleaner option when you don't need to reference the actions later. Keeping a list is useful when you want to modify or remove specific actions after creation.

Complete working example

Here's a slightly more fleshed-out version that gives each menu item its own behavior, so you can see how to connect different actions to different slots:

python

import sys

from PyQt6.QtWidgets import QApplication, QSystemTrayIcon, QMenu
from PyQt6.QtGui import QAction, QIcon


def on_action_triggered(text):
    print(f"Selected: {text}")


app = QApplication(sys.argv)
app.setQuitOnLastWindowClosed(False)

icon = QIcon.fromTheme("application")
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setVisible(True)

menu = QMenu()

entries = ["One", "Two", "Three"]
actions = []
for entry in entries:
    action = QAction(entry, menu)
    menu.addAction(action)
    # Use a default argument to capture the current value of entry
    action.triggered.connect(lambda checked, text=entry: on_action_triggered(text))
    actions.append(action)

# Add a separator and a quit option
menu.addSeparator()
quit_action = QAction("Quit", menu)
quit_action.triggered.connect(app.quit)
menu.addAction(quit_action)

tray.setContextMenu(menu)

sys.exit(app.exec())

Notice the lambda with a default argument (text=entry). This is a standard Python pattern for capturing the current loop variable's value inside a closure. Without text=entry, every lambda would reference the same entry variable and they'd all print "Three".

Conclusion

When you create Qt objects in a loop and they seem to disappear, the cause is almost always garbage collection. Python cleans up objects that no longer have references, and if you keep reassigning the same variable in a loop, only the last object survives.

The fix is to either store your objects in a list or give them a Qt parent so the C++ side manages their lifetime. This applies not just to QAction and menus, but to any Qt object you create dynamically — widgets, layouts, timers, and more. Once you're aware of this pattern, you'll recognize it immediately whenever things start vanishing.

For a complete guide to building system tray applications with menus, icons, and more, see the System Tray & Mac Menu Bar Applications tutorial. If you'd like to learn more about how signals, slots, and the lambda pattern used above work in practice, take a look at Signals, Slots & Events. To understand how actions, toolbars, and menus fit together in larger applications, the Actions, Toolbars & Menus tutorial covers these topics in depth. If you're new to PyQt6 and want to get your environment set up, see the PyQt6 installation guide for Windows.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

System Tray Icons Not Showing or Not Closing on Windows — Troubleshooting common issues with QSystemTrayIcon on Windows 10 and 11

2020-05-14T09:00:00+00:00

I'm following a system tray tutorial on Windows 10. When I run the example code, nothing happens — no icon shows up in the system tray, and I have to force the program to stop. Even when the icon does appear, quitting from the menu doesn't fully close the app — the icon lingers and I have to use Task Manager. Other examples from the web have the same problem. What's going on?

This is a surprisingly common issue, and there are a few different things that can cause it. The good news is that most of them are straightforward to fix once you know what to look for. Let's walk through the main causes and solutions.

The icon file is missing or in the wrong place

The most common reason a system tray icon doesn't appear at all on Windows is that the icon file can't be found. Unlike on some other platforms, Windows will silently show nothing if the icon path is wrong — no error, no placeholder, just an empty system tray.

If your code looks something like this:

python

tray = QSystemTrayIcon(QIcon("icon.png"))
tray.show()

Then icon.png must be in the same directory you're running the script from. That's the current working directory, which might not be the same as the folder your script lives in — especially if you're running from an IDE.

You can make the path more reliable by building it relative to the script file:

python

import os

basedir = os.path.dirname(__file__)
icon_path = os.path.join(basedir, "icon.png")
tray = QSystemTrayIcon(QIcon(icon_path))

Or, to avoid the icon-file problem entirely while you're testing, you can use one of Qt's built-in standard icons:

python

style = app.style()
icon = QIcon(style.standardIcon(QStyle.StandardPixmap.SP_ComputerIcon))
tray = QSystemTrayIcon(icon)

This guarantees you'll see something in the tray, which helps you confirm the rest of your code is working.

Windows hides new tray icons

Windows 10 and 11 sometimes hide system tray icons automatically. Your app might actually be running, but the icon is tucked away in the overflow area. Click the small upward arrow (^) on the taskbar to expand the hidden icons and check if your icon is there.

You can change this behavior in Windows Settings under Taskbar > Other system tray icons (Windows 11) or Taskbar settings > Select which icons appear on the taskbar (Windows 10).

IDEs can interfere with the event loop

This is the issue that causes the most confusion. If you're running your system tray app from inside an IDE like Spyder, Jupyter Notebook, or even PyCharm in certain configurations, the app may not shut down cleanly when you call app.quit(). The icon can linger in the tray, the process can hang, and you end up reaching for Task Manager.

Why does this happen? IDEs often run your Python code inside their own process or kernel. When your Qt application calls app.quit(), it stops the Qt event loop — but the IDE's surrounding process keeps running. The operating system sees the process is still alive, so it keeps the tray icon around.

The simplest way to confirm whether this is an IDE issue is to run your script from the command line:

python

python systray.py

If the app starts, shows the icon, and quits cleanly from the command line, then the problem is with your IDE, not your code.

Working around IDE issues

Here are a few approaches:

Run from the terminal. This is the most reliable option for testing system tray apps. Save your script to a .py file and run it with python yourscript.py.
Use PyCharm with a clean virtual environment. PyCharm's run configurations tend to behave more predictably than Spyder or Jupyter for GUI applications. Create a virtual environment, install PyQt6 (or PySide6), and run from there.
Avoid Jupyter Notebook for GUI apps. Jupyter runs code in a kernel that doesn't play well with Qt's event loop. It's a great tool for data exploration, but GUI application development is better done elsewhere.

Make sure you have a proper quit action

A system tray application has no main window by default, so there's no "X" button to close it. You need to provide a way for the user to quit — typically through the right-click context menu. Without this, the only way to stop the app is to kill the process.

Here's how to add a quit action to the context menu:

python

quit_action = QAction("Quit")
quit_action.triggered.connect(app.quit)
menu.addAction(quit_action)

Also, because there's no main window, you need to tell Qt not to quit when the last window is closed (since there was never a window to begin with):

python

app.setQuitOnLastWindowClosed(False)

Without this line, the application might exit immediately on some platforms, or behave unpredictably.

Remember to right-click

This catches people out more often than you'd expect. On Windows, system tray icons respond to right-click, not left-click. Right-clicking opens the context menu where your actions (like "Quit") live. Left-clicking a tray icon can trigger an "activated" signal, but only if you've connected something to it.

Complete working example

Here's a full, self-contained system tray application for PyQt6 that uses a built-in icon so you don't need any image files. You can copy this, save it as systray.py, and run it from the command line:

python

import sys

from PyQt6.QtGui import QAction, QIcon
from PyQt6.QtWidgets import (
    QApplication,
    QMenu,
    QStyle,
    QSystemTrayIcon,
)

app = QApplication(sys.argv)
app.setQuitOnLastWindowClosed(False)

# Use a built-in icon so we don't need an image file.
style = app.style()
icon = QIcon(style.standardIcon(QStyle.StandardPixmap.SP_ComputerIcon))

# Create the system tray icon.
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setToolTip("My Tray App")

# Build the right-click context menu.
menu = QMenu()

action_hello = QAction("Say Hello")
action_hello.triggered.connect(lambda: print("Hello from the system tray!"))
menu.addAction(action_hello)

menu.addSeparator()

action_quit = QAction("Quit")
action_quit.triggered.connect(app.quit)
menu.addAction(action_quit)

tray.setContextMenu(menu)

# Show the tray icon.
tray.setVisible(True)

sys.exit(app.exec())

Run it with:

$ python systray.py

You should see an icon appear in your system tray. Right-click it to see the menu. Choose "Say Hello" to print a message to the terminal, or "Quit" to close the app cleanly.

And here's the same example for PySide6:

python

import sys

from PySide6.QtGui import QAction, QIcon
from PySide6.QtWidgets import (
    QApplication,
    QMenu,
    QStyle,
    QSystemTrayIcon,
)

app = QApplication(sys.argv)
app.setQuitOnLastWindowClosed(False)

# Use a built-in icon so we don't need an image file.
style = app.style()
icon = QIcon(style.standardIcon(QStyle.StandardPixmap.SP_ComputerIcon))

# Create the system tray icon.
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setToolTip("My Tray App")

# Build the right-click context menu.
menu = QMenu()

action_hello = QAction("Say Hello")
action_hello.triggered.connect(lambda: print("Hello from the system tray!"))
menu.addAction(action_hello)

menu.addSeparator()

action_quit = QAction("Quit")
action_quit.triggered.connect(app.quit)
menu.addAction(action_quit)

tray.setContextMenu(menu)

# Show the tray icon.
tray.setVisible(True)

sys.exit(app.exec())

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Python GUIs - qsystemtrayicon

QSystemTrayIcon — Adding Menu Items in a Loop — Why dynamically created QActions disappear and how to fix it

The problem: disappearing menu items

Why this happens: Python garbage collection

The fix: keep references to your actions

An alternative: set the menu as the action's parent

Complete working example

Conclusion

System Tray Icons Not Showing or Not Closing on Windows — Troubleshooting common issues with QSystemTrayIcon on Windows 10 and 11

The icon file is missing or in the wrong place

Windows hides new tray icons

IDEs can interfere with the event loop

Working around IDE issues

Make sure you have a proper quit action

Remember to right-click

Complete working example