Python GUIs - styling

Custom style for menu items — How to use QWidgetAction to create menu items with custom background colors in PyQt6

2021-03-21T09:00:00+00:00

How can I create a menu item with a custom background color using QWidgetAction, while keeping the same behavior and style as regular QAction items?

When building menus in PyQt6, you might want to visually distinguish certain menu items — for example, by giving one a different background color. The standard QAction class doesn't directly support styling with stylesheets, so the usual approach is to use QWidgetAction, which lets you embed any widget inside a menu. The challenge is making that custom widget look and behave like a normal menu item.

Let's walk through how to do this properly.

The problem with a basic approach

A first attempt might look like embedding a QCheckBox inside a QWidgetAction and applying a stylesheet to it:

python

check_box = QCheckBox("My Item")
check_box.setStyleSheet("background-color: tomato;")

widget_action = QWidgetAction(self)
widget_action.setDefaultWidget(check_box)

This works partially — you get a checkbox in the menu with a red background. But the styling only covers the checkbox widget itself, not the full width of the menu item. The result looks awkward: the colored area doesn't stretch across the entire row, and the hover/highlight behavior doesn't match the other items.

To get the background color to fill the entire menu item row, you need to wrap your widget inside a container (like a QFrame or QWidget) and apply the background color to that container. This way the color spans the full width of the menu.

Here's a complete working example that demonstrates the approach:

python

import sys

from PyQt6.QtCore import Qt
from PyQt6.QtGui import QAction
from PyQt6.QtWidgets import (
    QApplication,
    QCheckBox,
    QFrame,
    QHBoxLayout,
    QMainWindow,
    QWidgetAction,
)


class MainWindow(QMainWindow):
    def __init__(self, parent=None):
        super().__init__(parent)

        self.setWindowTitle("Custom Menu Item")
        self.resize(640, 480)

        # Standard actions
        action1 = QAction("QAction Item 1", self)

        action2 = QAction("QAction Item 2", self)
        action2.setCheckable(True)

        action3 = QAction("QAction Item 3", self)

        # Custom styled menu item using QWidgetAction
        widget_action = QWidgetAction(self)

        # Create a container frame for the full-width background
        container = QFrame()
        container.setStyleSheet("background-color: tomato;")

        layout = QHBoxLayout(container)
        layout.setContentsMargins(4, 2, 4, 2)

        check_box = QCheckBox("QWidgetAction Item")
        check_box.setStyleSheet("background-color: tomato;")
        layout.addWidget(check_box)

        widget_action.setDefaultWidget(container)

        # Build the menu
        menu = self.menuBar().addMenu("Menu")
        menu.addAction(action1)
        menu.addAction(action2)
        menu.addAction(widget_action)
        menu.addAction(action3)


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

    window = MainWindow()
    window.show()

    sys.exit(app.exec())

With this setup, the QFrame container stretches to fill the full width of the menu, and the tomato background color covers the entire row.

Matching hover behavior

One thing you'll notice is that QWidgetAction items don't automatically get the same hover highlight as regular QAction items. The mouse hover styling is handled by the menu's style engine for standard actions, but custom widgets are on their own.

You can restore some of that behavior by using stylesheets on the container that respond to hover:

python

container.setStyleSheet("""
    QFrame {
        background-color: tomato;
    }
    QFrame:hover {
        background-color: #ff7f6e;
    }
""")

This gives the item a slightly lighter shade when the mouse hovers over it, providing visual feedback similar to standard menu items.

A more polished example

Here's the full example with hover behavior included:

python

import sys

from PyQt6.QtCore import Qt
from PyQt6.QtGui import QAction
from PyQt6.QtWidgets import (
    QApplication,
    QCheckBox,
    QFrame,
    QHBoxLayout,
    QMainWindow,
    QWidgetAction,
)


class MainWindow(QMainWindow):
    def __init__(self, parent=None):
        super().__init__(parent)

        self.setWindowTitle("Custom Menu Item")
        self.resize(640, 480)

        # Center the window on screen
        available_geometry = self.screen().availableGeometry()
        self.move(
            int((available_geometry.width() - self.width()) / 2),
            int((available_geometry.height() - self.height()) / 2),
        )

        # Standard actions
        action1 = QAction("QAction Item 1", self)
        action1.triggered.connect(lambda: print("Item 1 triggered"))

        action2 = QAction("QAction Item 2", self)
        action2.setCheckable(True)
        action2.toggled.connect(lambda checked: print(f"Item 2 toggled: {checked}"))

        action3 = QAction("QAction Item 3", self)
        action3.triggered.connect(lambda: print("Item 3 triggered"))

        # Custom styled menu item
        widget_action = QWidgetAction(self)

        container = QFrame()
        container.setStyleSheet(
            """
            QFrame {
                background-color: tomato;
            }
            QFrame:hover {
                background-color: #ff7f6e;
            }
            """
        )

        layout = QHBoxLayout(container)
        layout.setContentsMargins(4, 2, 4, 2)

        self.custom_check_box = QCheckBox("Custom Styled Item")
        self.custom_check_box.setStyleSheet(
            """
            QCheckBox {
                background-color: transparent;
                padding: 2px;
            }
            """
        )
        self.custom_check_box.toggled.connect(
            lambda checked: print(f"Custom item toggled: {checked}")
        )
        layout.addWidget(self.custom_check_box)

        widget_action.setDefaultWidget(container)

        # Build the menu
        menu = self.menuBar().addMenu("Menu")
        menu.addAction(action1)
        menu.addAction(action2)
        menu.addAction(widget_action)
        menu.addAction(action3)


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

    window = MainWindow()
    window.show()

    sys.exit(app.exec())

Notice that the checkbox itself has background-color: transparent so it inherits the container's background color rather than painting its own solid block on top.

One behavioral difference with QWidgetAction is that clicking the embedded widget does not automatically close the menu. With a standard QAction, clicking it triggers the action and closes the menu. With QWidgetAction, the menu stays open — which can actually be useful if you want users to toggle multiple checkboxes without having to reopen the menu each time.

If you do want the menu to close when the checkbox is clicked, you can connect the checkbox signal to the menu's close() method:

python

self.custom_check_box.toggled.connect(menu.close)

Add this after both the checkbox and the menu have been created. For more on how signals and connections work, see the Signals, Slots & Events tutorial.

Summary

Using QWidgetAction with a container QFrame gives you full control over the appearance of individual menu items. The container widget stretches to fill the menu width, and you can apply any stylesheet you like — background colors, fonts, borders, and more. Adding hover styles to the container keeps the visual feedback consistent with standard menu items, and connecting signals from your embedded widgets lets you respond to user interaction just like you would with regular actions.

If you're looking to further customize your application's appearance, you might also be interested in building custom widgets or arranging your UI with layouts.

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

Transparent TextBrowser — Creating a fading text effect in a QListView using custom model formatting

2021-02-12T09:00:00+00:00

I'm building an object detection app and every time something gets detected, I append text to a widget. I want the most recent text to appear prominently, with older entries gradually fading out. How can I achieve this fading text effect in PyQt6?

This is a great use case for Qt's Model/View architecture. Instead of trying to manually adjust the formatting of text inside a QTextEdit or QTextBrowser every time you add a new line, you can use a QListView backed by a model. The model holds your data, and a custom delegate controls how each item is drawn — including its color and opacity. When a new item is added, the view updates automatically, with the most recent entry appearing fully opaque and older entries fading out.

Let's walk through how to set this up.

Why QListView instead of QTextBrowser?

With a QTextBrowser or QTextEdit, you can change text color using .setTextColor(), but achieving a gradual fade across all previous lines means re-formatting the entire document every time you add a new entry. That gets awkward quickly.

A QListView with a QStandardItemModel is a much better fit. Each detected item becomes a row in the model, and you can apply formatting per-row based on its position. When you add a new entry, all the existing rows shift in visual weight automatically.

Setting up the model

Start with a basic QStandardItemModel connected to a QListView. Each time an object is detected, you append a new QStandardItem to the model.

python

from PyQt6.QtGui import QStandardItemModel, QStandardItem
from PyQt6.QtWidgets import QListView

model = QStandardItemModel()
list_view = QListView()
list_view.setModel(model)

# Adding an item
item = QStandardItem("Detected: cat")
model.appendRow(item)

That gives you a working list, but all items look the same. To create the fade effect, you need to control how items are drawn depending on how far they are from the bottom of the list.

Applying the fade with a custom delegate

Qt's delegate system lets you customize how each item in a view is painted. By subclassing QStyledItemDelegate, you can adjust the text color's alpha (transparency) based on each item's position relative to the most recent entry.

The last item in the list (the newest) gets full opacity. Each item above it gets progressively more transparent, fading out over a set number of visible rows.

python

from PyQt6.QtWidgets import QStyledItemDelegate
from PyQt6.QtGui import QColor


class FadingDelegate(QStyledItemDelegate):
    def __init__(self, fade_steps=10, parent=None):
        super().__init__(parent)
        self.fade_steps = fade_steps

    def initStyleOption(self, option, index):
        super().initStyleOption(option, index)
        model = index.model()
        total_rows = model.rowCount()
        row = index.row()

        # Distance from the last (newest) row
        distance = total_rows - 1 - row

        # Calculate alpha: 255 for the newest, fading toward 30 for older items
        min_alpha = 30
        if distance >= self.fade_steps:
            alpha = min_alpha
        else:
            alpha = max(
                min_alpha,
                255 - int((distance / self.fade_steps) * (255 - min_alpha)),
            )

        color = QColor(option.palette.color(option.palette.ColorRole.Text))
        color.setAlpha(alpha)
        option.palette.setColor(option.palette.ColorRole.Text, color)

The fade_steps parameter controls how many rows participate in the fade. Items older than fade_steps rows from the bottom settle at a low alpha value (30 in this case), making them very faint without disappearing entirely.

Connecting it all together

Set the delegate on your QListView, and each time you add an item, the entire list re-renders with the correct fading applied.

python

delegate = FadingDelegate(fade_steps=10)
list_view.setItemDelegate(delegate)

Whenever the model changes (a new row is appended), the view calls the delegate's paint logic for all visible items. The newest item appears at full opacity, and everything above it gradually fades.

Scrolling to the latest item

Since new detections go at the bottom, you'll want the view to scroll down automatically:

python

list_view.scrollToBottom()

Call this after each model.appendRow().

Complete working example

Here's a full application you can copy and run. It simulates object detections arriving every second using a QTimer, and displays them in a fading list.

python

import sys
import random

from PyQt6.QtCore import Qt, QTimer
from PyQt6.QtGui import QColor, QStandardItem, QStandardItemModel
from PyQt6.QtWidgets import (
    QApplication,
    QListView,
    QMainWindow,
    QStyledItemDelegate,
    QVBoxLayout,
    QWidget,
)


class FadingDelegate(QStyledItemDelegate):
    """Custom delegate that fades older items toward transparency."""

    def __init__(self, fade_steps=10, parent=None):
        super().__init__(parent)
        self.fade_steps = fade_steps

    def initStyleOption(self, option, index):
        super().initStyleOption(option, index)
        model = index.model()
        total_rows = model.rowCount()
        row = index.row()

        # How far this row is from the newest (bottom) row
        distance = total_rows - 1 - row

        # Full opacity for the newest, fading older items down to a minimum
        min_alpha = 30
        if distance >= self.fade_steps:
            alpha = min_alpha
        else:
            alpha = max(
                min_alpha,
                255 - int((distance / self.fade_steps) * (255 - min_alpha)),
            )

        color = QColor(option.palette.color(option.palette.ColorRole.Text))
        color.setAlpha(alpha)
        option.palette.setColor(option.palette.ColorRole.Text, color)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Fading Detection Log")
        self.resize(400, 500)

        # Set up the model and view
        self.model = QStandardItemModel()
        self.list_view = QListView()
        self.list_view.setModel(self.model)

        # Apply the fading delegate
        self.delegate = FadingDelegate(fade_steps=10)
        self.list_view.setItemDelegate(self.delegate)

        # Disable editing so it behaves like a log
        self.list_view.setEditTriggers(
            QListView.EditTrigger.NoEditTriggers
        )

        # Layout
        layout = QVBoxLayout()
        layout.addWidget(self.list_view)
        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

        # Simulate detections arriving every second
        self.objects = [
            "cat", "dog", "person", "car", "bicycle",
            "bird", "chair", "bottle", "phone", "laptop",
        ]
        self.timer = QTimer()
        self.timer.timeout.connect(self.add_detection)
        self.timer.start(1000)

    def add_detection(self):
        detected = random.choice(self.objects)
        item = QStandardItem(f"Detected: {detected}")
        item.setFlags(item.flags() & ~Qt.ItemFlag.ItemIsEditable)
        self.model.appendRow(item)
        self.list_view.scrollToBottom()


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

Run this and you'll see a live log where each new detection appears at full intensity, and older entries smoothly fade out above it. The fade_steps=10 means the last 10 entries participate in the gradient — adjust this number to control how quickly things fade.

Customizing the effect

There are several ways to adjust the look:

Change fade_steps: A smaller number (like 5) creates a sharper cutoff. A larger number (like 20) gives a more gradual fade.
Change min_alpha: Setting this to 0 would make old items fully invisible. Setting it to 100 keeps them somewhat readable.
Add bold to the newest item: In initStyleOption, you could check if distance == 0 and set the font to bold for the latest entry.
Use color changes: Instead of (or in addition to) transparency, you could shift the hue — for example, newest items in red, fading to gray.

Here's a quick example of making the newest entry bold:

python

def initStyleOption(self, option, index):
    super().initStyleOption(option, index)
    model = index.model()
    total_rows = model.rowCount()
    row = index.row()
    distance = total_rows - 1 - row

    # Bold the newest item
    if distance == 0:
        font = option.font
        font.setBold(True)
        option.font = font

    # ... rest of alpha calculation

Using a QListView with a custom delegate gives you a clean, maintainable way to present detection results with visual emphasis on what's new. The model/view pattern keeps your data and presentation separate, so you can change the visual style without touching your detection logic at all. If you're looking to build your own reusable widgets with custom painting, take a look at creating your own custom widgets in PyQt6. For more on how signals like QTimer.timeout connect to slots, see the signals and slots tutorial.

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

Styling PyQt/PySide Apps Installed via Pip on Linux — How to handle Qt styling and themes when distributing your Python GUI app through pip

2020-10-19T09:00:00+00:00

If you've built a PyQt or PySide application that looks great when you run it from your development environment, you might be surprised when you install it via pip and find it looking... not so great. On Linux especially, your app can end up with a flat, unstyled appearance — missing the native desktop look you expected.

This is a common issue, and it has a straightforward explanation. In this article, we'll look at why this happens and walk through several practical ways to fix it.

Why Does Styling Break on Linux?

When you run a Qt application on Linux, Qt tries to match the look and feel of your desktop environment (GNOME, KDE, etc.) by using a platform theme plugin. These plugins read your system's theme settings and apply them to your app's widgets — giving you native-looking buttons, scrollbars, and menus.

The problem is that these platform theme plugins are separate from Qt itself. They depend on system-level Qt libraries and desktop integration packages. When your app is installed via pip into a virtual environment (or a user install), it uses the PyQt5/PyQt6/PySide6 wheels from PyPI. These wheels bundle their own copy of the Qt libraries, but they don't include the platform theme plugins that integrate with your desktop environment.

The result? Qt falls back to a basic, unstyled look — sometimes called the "Windows 95" style.

Checking Your Current Style

Before applying fixes, it helps to see what's going on. You can check which style your app is using and what styles are available with a small script:

python

import sys
from PyQt6.QtWidgets import QApplication

app = QApplication(sys.argv)

print("Available styles:", app.style().objectName())
print("All styles:", [s for s in QApplication.style().objectName()])

# List all available style keys
from PyQt6.QtWidgets import QStyleFactory
print("Style factory keys:", QStyleFactory.keys())

On a Linux system using pip-installed PyQt6, you'll typically see only a handful of styles like Fusion and Windows, but not platform-native ones like gtk2 or Breeze.

Solution 1: Use the Fusion Style

The simplest and most portable solution is to explicitly set your app to use Qt's built-in Fusion style. Fusion is a modern, clean style that ships with Qt itself — so it's always available, regardless of how your app was installed.

python

import sys
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QPushButton,
    QVBoxLayout, QWidget, QCheckBox, QSlider,
    QComboBox, QLabel
)
from PyQt6.QtCore import Qt


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Fusion Style Example")

        layout = QVBoxLayout()
        layout.addWidget(QLabel("This app uses the Fusion style"))
        layout.addWidget(QPushButton("Click Me"))
        layout.addWidget(QCheckBox("Enable feature"))
        layout.addWidget(QSlider(Qt.Orientation.Horizontal))

        combo = QComboBox()
        combo.addItems(["Option A", "Option B", "Option C"])
        layout.addWidget(combo)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)


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

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

By calling app.setStyle("Fusion") before showing any windows, you guarantee a consistent, modern appearance on every platform — Linux, macOS, and Windows. If you're new to building Qt applications, see our guide to creating your first window with PyQt6 for the fundamentals.

Solution 2: Apply a Custom Qt Stylesheet (QSS)

If you want more control over the look of your app, you can use Qt Style Sheets (QSS). These work similarly to CSS in web development — you define rules that target widgets and set visual properties like colors, borders, padding, and fonts.

This approach is completely independent of the system theme, so it works reliably everywhere.

python

import sys
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QPushButton,
    QVBoxLayout, QWidget, QLabel
)


STYLESHEET = """
    QMainWindow {
        background-color: #2b2b2b;
    }
    QLabel {
        color: #ffffff;
        font-size: 14px;
        padding: 4px;
    }
    QPushButton {
        background-color: #4a86c8;
        color: white;
        border: none;
        border-radius: 4px;
        padding: 8px 16px;
        font-size: 13px;
    }
    QPushButton:hover {
        background-color: #5a96d8;
    }
    QPushButton:pressed {
        background-color: #3a76b8;
    }
"""


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Styled App")

        layout = QVBoxLayout()
        layout.addWidget(QLabel("Custom styled application"))
        layout.addWidget(QPushButton("Primary Action"))
        layout.addWidget(QPushButton("Secondary Action"))

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)


app = QApplication(sys.argv)
app.setStyle("Fusion")  # Use Fusion as the base style
app.setStyleSheet(STYLESHEET)

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

Setting Fusion as the base style before applying your stylesheet gives you a clean, neutral starting point that your QSS rules can build on top of.

Solution 3: Bundle a QSS File with Your Package

For larger projects, keeping your stylesheet in a separate .qss file makes it easier to maintain. You can bundle this file inside your Python package and load it at runtime.

Here's a typical project layout:

python

myapp/
├── __init__.py
├── __main__.py
├── main.py
└── styles/
    └── app.qss

Your app.qss file contains the stylesheet rules:

css

QPushButton {
    background-color: #4a86c8;
    color: white;
    border: none;
    border-radius: 4px;
    padding: 8px 16px;
}

QPushButton:hover {
    background-color: #5a96d8;
}

Then in your application code, load it using importlib.resources (Python 3.9+) or pathlib:

python

import sys
from pathlib import Path
from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton, QVBoxLayout, QWidget


def load_stylesheet():
    """Load the QSS stylesheet from the package's styles directory."""
    style_path = Path(__file__).parent / "styles" / "app.qss"
    if style_path.exists():
        return style_path.read_text()
    return ""


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Bundled Style App")

        layout = QVBoxLayout()
        layout.addWidget(QPushButton("Styled Button"))
        layout.addWidget(QPushButton("Another Button"))

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)


def main():
    app = QApplication(sys.argv)
    app.setStyle("Fusion")
    app.setStyleSheet(load_stylesheet())

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


if __name__ == "__main__":
    main()

To make sure your .qss file is included when you build your pip package, add it to your pyproject.toml:

toml

[tool.setuptools.package-data]
myapp = ["styles/*.qss"]

Or if you're using a MANIFEST.in:

python

recursive-include myapp/styles *.qss

This way the stylesheet travels with your package no matter how it's installed. For an alternative approach to bundling resources, you can also use the Qt Resource System to embed stylesheets and other assets directly into your application.

Solution 4: Set the Platform Theme via Environment Variable

If you want your pip-installed app to use the native system theme on Linux, you can try setting the QT_QPA_PLATFORMTHEME environment variable. This tells Qt which platform theme plugin to load.

For GNOME-based desktops:

bash

export QT_QPA_PLATFORMTHEME=gtk3

For KDE:

bash

export QT_QPA_PLATFORMTHEME=kde

You can also set this from within your application, before creating the QApplication:

python

import sys
import os

os.environ["QT_QPA_PLATFORMTHEME"] = "gtk3"

from PyQt6.QtWidgets import QApplication, QMainWindow

app = QApplication(sys.argv)
# ... rest of your app

However, this approach has a significant caveat: it only works if the corresponding platform theme plugin is installed on the user's system. For the gtk3 theme, the user would need the qt6-gtk-platformtheme package (or equivalent for their distribution) installed. Since you can't guarantee this for every user, this is less reliable than the Fusion or QSS approaches for apps distributed via pip.

Solution 5: Use QPalette with Fusion for a Custom Color Scheme

A middle ground between the plain Fusion style and a full stylesheet is to customize Fusion's color palette. This gives you a polished, consistent look while keeping the native widget behavior (hover effects, focus indicators, etc.) intact.

python

import sys
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QPushButton,
    QVBoxLayout, QWidget, QCheckBox, QLabel,
    QSlider, QComboBox, QLineEdit
)
from PyQt6.QtGui import QPalette, QColor
from PyQt6.QtCore import Qt


def create_dark_palette():
    """Create a dark color palette for the Fusion style."""
    palette = QPalette()

    # Base colors
    palette.setColor(QPalette.ColorRole.Window, QColor(53, 53, 53))
    palette.setColor(QPalette.ColorRole.WindowText, QColor(255, 255, 255))
    palette.setColor(QPalette.ColorRole.Base, QColor(35, 35, 35))
    palette.setColor(QPalette.ColorRole.AlternateBase, QColor(53, 53, 53))
    palette.setColor(QPalette.ColorRole.ToolTipBase, QColor(25, 25, 25))
    palette.setColor(QPalette.ColorRole.ToolTipText, QColor(255, 255, 255))
    palette.setColor(QPalette.ColorRole.Text, QColor(255, 255, 255))
    palette.setColor(QPalette.ColorRole.Button, QColor(53, 53, 53))
    palette.setColor(QPalette.ColorRole.ButtonText, QColor(255, 255, 255))
    palette.setColor(QPalette.ColorRole.BrightText, QColor(255, 0, 0))
    palette.setColor(QPalette.ColorRole.Link, QColor(42, 130, 218))
    palette.setColor(QPalette.ColorRole.Highlight, QColor(42, 130, 218))
    palette.setColor(QPalette.ColorRole.HighlightedText, QColor(35, 35, 35))

    # Disabled state
    palette.setColor(
        QPalette.ColorGroup.Disabled,
        QPalette.ColorRole.WindowText,
        QColor(127, 127, 127),
    )
    palette.setColor(
        QPalette.ColorGroup.Disabled,
        QPalette.ColorRole.Text,
        QColor(127, 127, 127),
    )
    palette.setColor(
        QPalette.ColorGroup.Disabled,
        QPalette.ColorRole.ButtonText,
        QColor(127, 127, 127),
    )
    palette.setColor(
        QPalette.ColorGroup.Disabled,
        QPalette.ColorRole.HighlightedText,
        QColor(127, 127, 127),
    )

    return palette


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Dark Fusion Theme")

        layout = QVBoxLayout()
        layout.addWidget(QLabel("Dark Fusion palette example"))
        layout.addWidget(QLineEdit("Editable text"))
        layout.addWidget(QPushButton("Enabled Button"))

        disabled_btn = QPushButton("Disabled Button")
        disabled_btn.setEnabled(False)
        layout.addWidget(disabled_btn)

        layout.addWidget(QCheckBox("A checkbox option"))
        layout.addWidget(QSlider(Qt.Orientation.Horizontal))

        combo = QComboBox()
        combo.addItems(["First", "Second", "Third"])
        layout.addWidget(combo)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)


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

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

The QPalette approach works well because Fusion respects the palette colors throughout all its widget rendering. You get a cohesive dark (or custom-colored) theme with proper disabled states, hover effects, and focus indicators — all without writing a single line of QSS.

Which Approach Should You Use?

Here's a quick summary to help you decide:

Approach	Pros	Cons
Fusion style	Always available, zero config	Doesn't match native desktop theme
QSS stylesheet	Full visual control, portable	Can be verbose for complex UIs
Bundled QSS file	Maintainable, separates style from logic	Requires packaging setup
Environment variable	Can get native theme	Depends on user's system packages
QPalette + Fusion	Clean, native-feeling widget behavior	Limited to color changes

For most pip-distributed applications, Fusion style combined with either a QPalette or a QSS stylesheet is the most reliable approach. It gives you a consistent, professional appearance across all Linux distributions, as well as on macOS and Windows, without depending on anything outside your package.

The reality of distributing Python GUI apps via pip on Linux is that you can't rely on the system's Qt theme integration. By taking control of your styling explicitly, you ensure your users get a polished experience regardless of their desktop environment or how they installed your app. If you're ready to package your application for distribution, see our guide on packaging PyQt6 apps for Linux with PyInstaller for the next steps.

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

Python GUIs - styling

Custom style for menu items — How to use QWidgetAction to create menu items with custom background colors in PyQt6

The problem with a basic approach

Using a container widget for full-width styling

Matching hover behavior

A more polished example

A note about menu closing behavior

Summary

Transparent TextBrowser — Creating a fading text effect in a QListView using custom model formatting

Why QListView instead of QTextBrowser?

Setting up the model

Applying the fade with a custom delegate

Connecting it all together

Scrolling to the latest item

Complete working example

Customizing the effect

Styling PyQt/PySide Apps Installed via Pip on Linux — How to handle Qt styling and themes when distributing your Python GUI app through pip

Why Does Styling Break on Linux?

Checking Your Current Style

Solution 1: Use the Fusion Style

Solution 2: Apply a Custom Qt Stylesheet (QSS)

Solution 3: Bundle a QSS File with Your Package

Solution 4: Set the Platform Theme via Environment Variable

Solution 5: Use QPalette with Fusion for a Custom Color Scheme

Which Approach Should You Use?