Of course! qdarkstyle is a fantastic, popular, and easy-to-use library for applying a dark theme to your Qt-based applications, including those built with PyQt, PySide, or PySide2/6.

Here's a comprehensive guide covering everything you need to know about using qdarkstyle.

What is qdarkstyle?

qdarkstyle is a Python library that provides a dark, theme for Qt applications. It works by dynamically patching the Qt stylesheets at runtime. This means it can style a wide range of standard Qt widgets, including:

• Buttons, Labels, Line Edits
• Combo Boxes, Spin Boxes, Sliders
• Checkboxes, Radio Buttons
• Tab Widgets, Toolbars, Menus
• Tables, Tree Views, List Views
• Progress Bars, Group Boxes
• And many more!

Key Features

• Easy to Use: Just two lines of code to apply a complete dark theme.
• Comprehensive: Styles most standard Qt widgets.
• Customizable: You can tweak colors and disable certain widget styling.
• Cross-Platform: Works on Windows, macOS, and Linux.
• Framework Agnostic: Compatible with PyQt5, PyQt6, PySide2, and PySide6.

Installation

First, you need to install the library. It's available on PyPI.

pip install qdarkstyle

If you don't have a Qt binding yet, you'll also need one of the following:

• pip install PyQt5
• pip install PyQt6
• pip install PySide2
• pip install PySide6

How to Use It (The Basics)

The core idea is to import the library, apply the style to your application, and then create your widgets as usual. The style will automatically be applied.

Example 1: PyQt5 Application

This is the most common and straightforward example.

import sys
import qdarkstyle
from PyQt5.QtWidgets import QApplication, QMainWindow, QLabel, QVBoxLayout, QWidget
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QDarkStyle Demo")
        self.setGeometry(100, 100, 400, 300)
        # --- Create a central widget and layout ---
        central_widget = QWidget()
        self.setCentralWidget(central_widget)
        layout = QVBoxLayout(central_widget)
        # --- Add some widgets to see the styling ---
        label = QLabel("This is a QLabel in a dark theme.")
        label.setStyleSheet("font-size: 18px; font-weight: bold;") # Custom styling still works
        layout.addWidget(label)
        button = QPushButton("Click Me")
        layout.addWidget(button)
        checkbox = QCheckBox("Enable Feature")
        layout.addWidget(checkbox)
        combobox = QComboBox()
        combobox.addItems(["Option 1", "Option 2", "Option 3"])
        layout.addWidget(combobox)
        spacer = QSpacerItem(20, 40, QSizePolicy.Minimum, QSizePolicy.Expanding)
        layout.addItem(spacer)
if __name__ == "__main__":
    # 1. Create the QApplication
    app = QApplication(sys.argv)
    # 2. Apply the dark style
    app.setStyleSheet(qdarkstyle.load_stylesheet())
    # 3. Create and show the main window
    window = MainWindow()
    window.show()
    # 4. Run the application's event loop
    sys.exit(app.exec_())

Example 2: PySide6 Application

The code is almost identical, you just change the import statement.

import sys
import qdarkstyle
from PySide6.QtWidgets import QApplication, QMainWindow, QLabel, QPushButton, QCheckBox, QComboBox, QVBoxLayout, QWidget, QSpacerItem, QSizePolicy
class MainWindow(QMainWindow):
    # ... (The class definition is exactly the same as the PyQt5 example) ...
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QDarkStyle Demo (PySide6)")
        self.setGeometry(100, 100, 400, 300)
        central_widget = QWidget()
        self.setCentralWidget(central_widget)
        layout = QVBoxLayout(central_widget)
        label = QLabel("This is a QLabel in a dark theme.")
        label.setStyleSheet("font-size: 18px; font-weight: bold;")
        layout.addWidget(label)
        button = QPushButton("Click Me")
        layout.addWidget(button)
        checkbox = QCheckBox("Enable Feature")
        layout.addWidget(checkbox)
        combobox = QComboBox()
        combobox.addItems(["Option 1", "Option 2", "Option 3"])
        layout.addWidget(combobox)
if __name__ == "__main__":
    app = QApplication(sys.argv)
    # The line to apply the style is the same!
    app.setStyleSheet(qdarkstyle.load_stylesheet())
    window = MainWindow()
    window.show()
    sys.exit(app.exec())

Customization and Advanced Usage

qdarkstyle is not just a one-size-fits-all solution. You can customize it to better fit your needs.

Choosing a Specific Theme

qdarkstyle comes with a few different palettes. You can choose between them.

• qdarkstyle.load_stylesheet(): Uses the default "dark" theme.
• qdarkstyle.load_stylesheet_pyqt5(): Explicitly for PyQt5.
• qdarkstyle.load_stylesheet_pyside6(): Explicitly for PySide6.
• qdarkstyle.load_stylesheet(theme='dark'): The default.
• qdarkstyle.load_stylesheet(theme='light'): A light theme version.
• qdarkstyle.load_stylesheet(theme='dark_alternative'): An alternative dark palette.

Example:

# Use the alternative dark theme
app.setStyleSheet(qdarkstyle.load_stylesheet(theme='dark_alternative'))

Disabling Styling for Specific Widgets

Sometimes you might want a specific widget to use the default system style instead of the qdarkstyle theme. You can achieve this by setting an empty stylesheet for that widget.

from PyQt5.QtWidgets import QPushButton
# ... inside your MainWindow ...
my_button = QPushButton("I am a default button")
my_button.setStyleSheet("") # This overrides the global dark style
layout.addWidget(my_button)

Combining with Custom Styles

You can apply your own custom stylesheets after loading qdarkstyle. Your custom styles will override the qdarkstyle defaults.

# Apply the dark theme first
app.setStyleSheet(qdarkstyle.load_stylesheet())
# Now, add your custom styles
custom_style = """
QLabel {
    color: #00ff00; /* Make labels bright green */
    background-color: #001a00; /* Dark green background */
}
QPushButton {
    border: 2px solid #00ff00;
    border-radius: 5px;
}
"""
app.setStyleSheet(app.styleSheet() + custom_style)

Troubleshooting: "My custom styles aren't working!"

The most common issue is that qdarkstyle's styles are very specific and can override your more general ones. To fix this, increase the specificity of your CSS selectors.

Bad (Low Specificity):

QPushButton {
    color: red;
}

This might be overridden by qdarkstyle's QPushButton { color: #bbbbbb; }.

Good (High Specificity):

/* Be more specific by targeting the main window or a central widget */
#myMainWindow QPushButton {
    color: red;
}
/* Or target a specific class of button */
QPushButton#mySpecialButton {
    color: red;
    background-color: #333333;
}

Alternatives to qdarkstyle

While qdarkstyle is excellent, it's good to know other options.

1. Qt Style Sheets (Manual): You can write your own stylesheets from scratch. This gives you maximum control but is a lot of work. qdarkstyle is essentially a very well-written, comprehensive Qt stylesheet.

2. Qt Material: A library that provides Material Design themes for Qt applications. It's another great option, offering a different aesthetic (Google's Material Design) than qdarkstyle's native look.

3. QDarkPalette (A component of qdarkstyle): If you only want the color palette and not the full widget styling, you can use QDarkPalette to manually set the application's palette.

from qdarkstyle import QDarkPalette
from PyQt5.QtWidgets import QApplication
from PyQt5.QtGui import QPalette
app = QApplication(sys.argv)
palette = QDarkPalette()
app.palette().setColor(QPalette.Window, palette.color(QPalette.Window))
# ... and so on for other roles ...

Summary