Python GUIs - Context-Menu

Implementing "Open With" Context Menus in PyQt6 — Query your Linux desktop for available applications and let users choose how to open files

2021-03-25T09:00:00+00:00

I'm finishing an application that has a custom context menu with "Open" and "Open Containing Folder" working. I can't seem to get an "Open With" option like you see in file explorers. Depending on the file type there would be different options — so I don't think we're talking about predefined lists, but rather something extracted from the host OS. Any help with "Open With" would be greatly appreciated.

When you right-click a file in a file manager like Nemo or Nautilus, you see a list of applications that can handle that file type. That list comes from the operating system's knowledge of installed applications and their supported MIME types. To recreate this in your own PyQt6 application, you need to query that same information.

On Linux desktops (GNOME, Cinnamon, XFCE, etc.), this information is managed through the freedesktop.org standards. The gio module from PyGObject (the Python bindings for GLib/GIO) gives you clean access to all of it — which applications support a given MIME type, what their names and icons are, and how to launch them.

Let's walk through building this step by step.

Understanding the moving parts

There are three things you need to do:

Determine the MIME type of a file (e.g., image/png, text/plain).
Find the applications that can open that MIME type.
Launch the chosen application with the file as an argument.

The GIO library handles all three. If you're on a Linux desktop with GTK-based tools installed, you almost certainly have gi (PyGObject) available already. If not, you can install it:

sudo apt install python3-gi gir1.2-gio-2.0

Getting the MIME type for a file

GIO can detect the MIME type of a file by inspecting its contents and name:

python

from gi.repository import Gio

def get_mime_type(filepath):
    """Return the MIME type string for a given file path."""
    gfile = Gio.File.new_for_path(filepath)
    info = gfile.query_info(
        "standard::content-type", Gio.FileQueryInfoFlags.NONE, None
    )
    return info.get_content_type()

Calling get_mime_type("/home/user/photo.png") would return something like "image/png".

Finding applications for a MIME type

Once you have the MIME type, you can ask GIO for a list of applications that support it:

python

from gi.repository import Gio

def get_apps_for_mime(mime_type):
    """Return a list of Gio.AppInfo objects that can open the given MIME type."""
    return Gio.AppInfo.get_all_for_type(mime_type)

Each Gio.AppInfo object gives you the application's display name (e.g., "GIMP Image Editor"), its icon, and the ability to launch it with a file.

Launching an application with a file

To open a file with a specific application:

python

from gi.repository import Gio

def open_file_with_app(app_info, filepath):
    """Launch the given app with the specified file."""
    gfile = Gio.File.new_for_path(filepath)
    app_info.launch([gfile], None)

That's the complete backend. Now let's wire it into a PyQt6 context menu.

The idea is straightforward: when the user right-clicks, you build a QMenu that includes an "Open With" submenu. That submenu is populated dynamically based on the file they clicked on. If you're new to building menus and actions in PyQt6, the Actions, Toolbars & Menus tutorial covers the fundamentals.

Here's a minimal example using a QListWidget to display some file paths. Right-clicking a file shows the context menu with an "Open With" submenu:

python

import sys
import os
import subprocess

from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import (
    QApplication,
    QListWidget,
    QMainWindow,
    QMenu,
)

from gi.repository import Gio


def get_mime_type(filepath):
    """Return the MIME type string for a given file path."""
    gfile = Gio.File.new_for_path(filepath)
    info = gfile.query_info(
        "standard::content-type", Gio.FileQueryInfoFlags.NONE, None
    )
    return info.get_content_type()


def get_apps_for_mime(mime_type):
    """Return a list of Gio.AppInfo objects for the given MIME type."""
    return Gio.AppInfo.get_all_for_type(mime_type)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Open With Example")
        self.resize(500, 400)

        self.list_widget = QListWidget()
        self.setCentralWidget(self.list_widget)

        # Add some example files — replace these with real paths on your system.
        example_files = [
            os.path.expanduser("~/Documents"),
            os.path.expanduser("~/Pictures"),
        ]

        # Walk through directories and add files.
        for folder in example_files:
            if os.path.isdir(folder):
                for entry in os.listdir(folder):
                    full_path = os.path.join(folder, entry)
                    if os.path.isfile(full_path):
                        self.list_widget.addItem(full_path)

        self.list_widget.setContextMenuPolicy(
            Qt.ContextMenuPolicy.CustomContextMenu
        )
        self.list_widget.customContextMenuRequested.connect(
            self.show_context_menu
        )

    def show_context_menu(self, position):
        item = self.list_widget.itemAt(position)
        if item is None:
            return

        filepath = item.text()

        menu = QMenu(self)

        # "Open" action — uses the system default application.
        open_action = menu.addAction("Open")
        open_action.triggered.connect(
            lambda: self.open_default(filepath)
        )

        # "Open Containing Folder" action.
        open_folder_action = menu.addAction("Open Containing Folder")
        open_folder_action.triggered.connect(
            lambda: self.open_containing_folder(filepath)
        )

        # "Open With" submenu.
        open_with_menu = menu.addMenu("Open With...")
        self.populate_open_with_menu(open_with_menu, filepath)

        menu.exec(self.list_widget.mapToGlobal(position))

    def populate_open_with_menu(self, submenu, filepath):
        """Fill the 'Open With' submenu with available applications."""
        try:
            mime_type = get_mime_type(filepath)
        except Exception:
            no_apps = submenu.addAction("(unable to detect file type)")
            no_apps.setEnabled(False)
            return

        apps = get_apps_for_mime(mime_type)

        if not apps:
            no_apps = submenu.addAction("(no applications found)")
            no_apps.setEnabled(False)
            return

        for app_info in apps:
            app_name = app_info.get_display_name()
            action = submenu.addAction(app_name)
            # Use a default argument in the lambda to capture the current
            # app_info, avoiding the common closure-in-a-loop issue.
            action.triggered.connect(
                lambda checked, ai=app_info: self.open_with_app(
                    ai, filepath
                )
            )

    def open_default(self, filepath):
        """Open the file with the system default application."""
        subprocess.Popen(["xdg-open", filepath])

    def open_containing_folder(self, filepath):
        """Open the folder containing the file."""
        folder = os.path.dirname(filepath)
        subprocess.Popen(["xdg-open", folder])

    def open_with_app(self, app_info, filepath):
        """Launch a specific application with the given file."""
        gfile = Gio.File.new_for_path(filepath)
        try:
            app_info.launch([gfile], None)
        except Exception as e:
            print(f"Failed to launch {app_info.get_display_name()}: {e}")


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

You can copy this, update the example_files list with folders that exist on your system, and run it. Right-clicking any file in the list will show a context menu with the full "Open With..." submenu populated from your installed applications.

How the lambda capture works

You might have noticed this pattern in the loop:

python

action.triggered.connect(
    lambda checked, ai=app_info: self.open_with_app(ai, filepath)
)

The ai=app_info part is a default argument that captures the current value of app_info at the time the lambda is created. Without it, every menu action would end up using the last value of app_info from the loop — a common and frustrating Python gotcha when connecting signals inside loops. For more on how signals and slots work in PyQt6, including lambda connections, see Signals, Slots & Events.

Adding application icons

You can make the submenu look more polished by including application icons. GIO provides icon information through app_info.get_icon(), and you can resolve this to a file path using the system icon theme. Here's an updated version of the populate_open_with_menu method:

python

from PyQt6.QtGui import QIcon


def populate_open_with_menu(self, submenu, filepath):
    """Fill the 'Open With' submenu with available applications."""
    try:
        mime_type = get_mime_type(filepath)
    except Exception:
        action = submenu.addAction("(unable to detect file type)")
        action.setEnabled(False)
        return

    apps = get_apps_for_mime(mime_type)

    if not apps:
        action = submenu.addAction("(no applications found)")
        action.setEnabled(False)
        return

    for app_info in apps:
        app_name = app_info.get_display_name()
        icon = app_info.get_icon()

        action = submenu.addAction(app_name)

        # Try to load the icon from the system icon theme.
        if icon is not None and hasattr(icon, "get_names"):
            for icon_name in icon.get_names():
                qt_icon = QIcon.fromTheme(icon_name)
                if not qt_icon.isNull():
                    action.setIcon(qt_icon)
                    break

        action.triggered.connect(
            lambda checked, ai=app_info: self.open_with_app(
                ai, filepath
            )
        )

QIcon.fromTheme() looks up icons from the system's icon theme (the same one your desktop environment uses), so the icons in your submenu will match what users see in their native file manager.

A note on cross-platform compatibility

This approach relies on GIO, which is a GLib/GNOME technology. It works well on Linux desktops that follow freedesktop.org standards, which includes Linux Mint, Ubuntu, Fedora, and most others.

If you need cross-platform support:

On macOS, you can use subprocess.Popen(["open", "-a", app_name, filepath]) and query available apps using NSWorkspace via PyObjC.
On Windows, you can use the SHAssocEnumHandlers COM API or query the registry, though this is more involved.

For a Linux-focused application, GIO is the natural and reliable choice. When you're ready to distribute your finished application, take a look at packaging PyQt6 apps for Linux with PyInstaller to create standalone executables.

Complete working example

Here is the full application with icons included. If you need help setting up your PyQt6 development environment first, see the PyQt6 installation guide for Linux.

python

import sys
import os
import subprocess

from PyQt6.QtCore import Qt
from PyQt6.QtGui import QIcon
from PyQt6.QtWidgets import (
    QApplication,
    QListWidget,
    QMainWindow,
    QMenu,
)

from gi.repository import Gio


def get_mime_type(filepath):
    """Return the MIME type string for a given file path."""
    gfile = Gio.File.new_for_path(filepath)
    info = gfile.query_info(
        "standard::content-type", Gio.FileQueryInfoFlags.NONE, None
    )
    return info.get_content_type()


def get_apps_for_mime(mime_type):
    """Return a list of Gio.AppInfo objects for the given MIME type."""
    return Gio.AppInfo.get_all_for_type(mime_type)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Open With Example")
        self.resize(500, 400)

        self.list_widget = QListWidget()
        self.setCentralWidget(self.list_widget)

        # Add files from common directories. Update these paths to
        # match your system.
        search_dirs = [
            os.path.expanduser("~/Documents"),
            os.path.expanduser("~/Pictures"),
            os.path.expanduser("~/Downloads"),
        ]

        for folder in search_dirs:
            if os.path.isdir(folder):
                for entry in sorted(os.listdir(folder)):
                    full_path = os.path.join(folder, entry)
                    if os.path.isfile(full_path):
                        self.list_widget.addItem(full_path)

        self.list_widget.setContextMenuPolicy(
            Qt.ContextMenuPolicy.CustomContextMenu
        )
        self.list_widget.customContextMenuRequested.connect(
            self.show_context_menu
        )

    def show_context_menu(self, position):
        item = self.list_widget.itemAt(position)
        if item is None:
            return

        filepath = item.text()
        menu = QMenu(self)

        # Open with default application.
        open_action = menu.addAction("Open")
        open_action.triggered.connect(
            lambda: self.open_default(filepath)
        )

        # Open containing folder.
        open_folder_action = menu.addAction("Open Containing Folder")
        open_folder_action.triggered.connect(
            lambda: self.open_containing_folder(filepath)
        )

        menu.addSeparator()

        # Open With submenu.
        open_with_menu = menu.addMenu("Open With...")
        self.populate_open_with_menu(open_with_menu, filepath)

        menu.exec(self.list_widget.mapToGlobal(position))

    def populate_open_with_menu(self, submenu, filepath):
        """Fill the 'Open With' submenu with available applications."""
        try:
            mime_type = get_mime_type(filepath)
        except Exception:
            action = submenu.addAction("(unable to detect file type)")
            action.setEnabled(False)
            return

        apps = get_apps_for_mime(mime_type)

        if not apps:
            action = submenu.addAction("(no applications found)")
            action.setEnabled(False)
            return

        for app_info in apps:
            app_name = app_info.get_display_name()
            icon = app_info.get_icon()

            action = submenu.addAction(app_name)

            # Try to set the application's icon from the system theme.
            if icon is not None and hasattr(icon, "get_names"):
                for icon_name in icon.get_names():
                    qt_icon = QIcon.fromTheme(icon_name)
                    if not qt_icon.isNull():
                        action.setIcon(qt_icon)
                        break

            action.triggered.connect(
                lambda checked, ai=app_info: self.open_with_app(
                    ai, filepath
                )
            )

    def open_default(self, filepath):
        """Open the file using the system default application."""
        subprocess.Popen(["xdg-open", filepath])

    def open_containing_folder(self, filepath):
        """Open the directory that contains the file."""
        folder = os.path.dirname(filepath)
        subprocess.Popen(["xdg-open", folder])

    def open_with_app(self, app_info, filepath):
        """Launch a specific application to open the given file."""
        gfile = Gio.File.new_for_path(filepath)
        try:
            app_info.launch([gfile], None)
        except Exception as e:
            print(f"Failed to launch {app_info.get_display_name()}: {e}")


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

Run this application, and you'll see a list of files from your home directories. Right-click any file and you'll get a context menu with "Open", "Open Containing Folder", and an "Open With..." submenu listing every application your system knows can handle that file type — just like a native file manager.

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

How to Show a QMenu Title in PyQt6 — Adding visible titles to your context menus using QLabel, QWidgetAction, and other approaches

2020-05-24T09:00:00+00:00

If you've ever tried to set a title on a QMenu in PyQt6, you've probably noticed something frustrating: calling setTitle() on a menu doesn't actually display a title on the popup itself. The title property on QMenu is used for something else entirely — it's the text that appears when the menu is added to a QMenuBar (like "File", "Edit", etc.). When you show a QMenu as a standalone context menu, that title is invisible.

So how do you show a visible heading at the top of a context menu? There are a few approaches, each with their own trade-offs. In this tutorial, we'll walk through all of them and finish with the most flexible solution: embedding a QLabel widget directly in the menu using QWidgetAction.

Why `setTitle()` Doesn't Work

When you create a QMenu and call setTitle(), you're setting the label that would appear on a menu bar. For example:

python

menu = QMenu()
menu.setTitle("My Menu")

If you added this menu to a QMenuBar, you'd see "My Menu" as a clickable item on the bar. But when you show this menu as a popup context menu (using .show() or .exec()), that title is nowhere to be seen.

This catches a lot of people off guard, but once you know why it works this way, you can reach for the right solution.

Using `addSection()`

Qt provides a built-in method called addSection() that's designed to add labeled section headers to a menu. You might think this is exactly what you need — and depending on your platform and theme, it might be.

python

menu = QMenu()
menu.addSection("My Menu Title")
menu.addAction("Option 1")
menu.addAction("Option 2")

The catch is that addSection() renders differently depending on the platform style. On macOS and Windows native themes, it often looks identical to a plain separator line — the text simply doesn't show up.

The one reliable way to make addSection() visible is to use the Fusion style, which is Qt's built-in cross-platform theme:

python

app = QApplication(sys.argv)
app.setStyle("Fusion")

With Fusion active, addSection() displays the section text alongside a separator line, which looks quite nice. The downside is that Fusion doesn't match the native look and feel of any operating system, so your entire application will look slightly different from other apps on the user's desktop.

Using a Disabled Action

A simpler workaround is to add a regular action and then disable it. A disabled action shows its text but appears grayed out and can't be clicked:

python

menu = QMenu()
title_action = menu.addAction("My Menu Title")
title_action.setDisabled(True)
menu.addSeparator()
menu.addAction("Option 1")
menu.addAction("Option 2")

This works on all platforms and themes. The text shows up, and users can't accidentally click on it. However, it looks like a disabled menu item, which could be confusing — users might wonder what they need to do to enable it.

Using a QLabel with QWidgetAction

The most flexible approach is to embed a QLabel widget directly into the menu using QWidgetAction. This lets you fully control the appearance of the title — you can center it, make it bold, change its background color, and more.

Here's how it works. First, create a QLabel with the text you want:

python

from PyQt6.QtWidgets import QLabel, QWidgetAction, QSizePolicy
from PyQt6.QtCore import Qt

label = QLabel("My Menu Title")
label.setAlignment(Qt.AlignCenter)
label.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Expanding)

Then wrap the label in a QWidgetAction and add it to the menu. Note that the parent of the QWidgetAction should be the menu itself (not the label) — this ensures proper memory management and avoids crashes:

python

menu = QMenu()

widget_action = QWidgetAction(menu)
widget_action.setDefaultWidget(label)
menu.addAction(widget_action)

menu.addSeparator()
menu.addAction("Option 1")
menu.addAction("Option 2")

You can style the label however you like. For example, to make it bold with a colored background:

python

label.setStyleSheet("font-weight: bold; background-color: #e0e0e0; padding: 4px;")

This approach works reliably across all platforms and themes, and gives you complete control over how the title looks.

Complete Working Example

Here's a full example that demonstrates all three approaches side by side. Right-click anywhere in the window to see a context menu with a QLabel-based title. You can uncomment the alternative approaches to compare them.

python

import sys
from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QMenu, QLabel,
    QWidgetAction, QSizePolicy
)


class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()
        self.setWindowTitle("QMenu Title Example")
        self.resize(400, 300)

        label = QLabel("Right-click anywhere in this window")
        label.setAlignment(Qt.AlignCenter)
        self.setCentralWidget(label)

    def contextMenuEvent(self, event):
        menu = QMenu(self)

        # --- Approach 1: QLabel with QWidgetAction (recommended) ---
        title_label = QLabel("My Menu Title")
        title_label.setAlignment(Qt.AlignCenter)
        title_label.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Expanding)
        title_label.setStyleSheet(
            "font-weight: bold; padding: 4px;"
        )

        title_action = QWidgetAction(menu)
        title_action.setDefaultWidget(title_label)
        menu.addAction(title_action)

        # --- Approach 2: Disabled action (uncomment to try) ---
        # title_action = menu.addAction("My Menu Title")
        # title_action.setDisabled(True)

        # --- Approach 3: addSection (uncomment to try, works best with Fusion) ---
        # menu.addSection("My Menu Title")

        menu.addSeparator()
        menu.addAction("Select All")
        menu.addAction("Copy")
        menu.addAction("Paste")
        menu.addSeparator()
        menu.addAction("Settings...")

        menu.exec(event.globalPos())


if __name__ == "__main__":
    app = QApplication(sys.argv)

    # Uncomment the next line to try the Fusion style with addSection()
    # app.setStyle("Fusion")

    window = MainWindow()
    window.show()
    sys.exit(app.exec())

When you run this and right-click in the window, you'll see a context menu with a bold, centered title at the top.

The QWidgetAction approach is the most versatile because you have full control over the widget. You could swap the QLabel for any widget — even a small layout with an icon and text, if you wanted to get creative.

Summary

The title property on QMenu is meant for menu bar display, not for context menu headings. To show a visible title on a popup menu, you have three options:

addSection() — built-in but only visible with certain styles (like Fusion).
Disabled action — simple but looks like a grayed-out menu item.
QWidgetAction with a QLabel — looks like a heading and gives you full control over the title's appearance.

Usually QWidgetAction is the one you want to go with. For more on building menus, toolbars, and actions in PyQt6, see our tutorial on Actions, Toolbars & Menus in PyQt6. If you're building custom widgets like styled labels or other UI elements, you may also find our guide to creating your own custom widgets in PyQt6 helpful.

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

Python GUIs - Context-Menu

Implementing "Open With" Context Menus in PyQt6 — Query your Linux desktop for available applications and let users choose how to open files

Understanding the moving parts

Getting the MIME type for a file

Finding applications for a MIME type

Launching an application with a file

Building the context menu in PyQt6

How the lambda capture works

Adding application icons

A note on cross-platform compatibility

Complete working example

How to Show a QMenu Title in PyQt6 — Adding visible titles to your context menus using QLabel, QWidgetAction, and other approaches

Why setTitle() Doesn't Work

Using addSection()

Using a Disabled Action

Using a QLabel with QWidgetAction

Complete Working Example

Summary

Why `setTitle()` Doesn't Work

Using `addSection()`