PyQtDarkTheme Documentation

PyQtDarkTheme provides a flat dark and light theme for Qt-based applications using PySide or PyQt. It is designed to balance colors for easy viewing in daylight and includes features such as:

• Theme Support: Provides both dark and light themes, including QPalette support.
• Cross-Framework Compatibility: Works with PySide, PyQt, and is compatible with PyInstaller.
• OS Integration: Can sync with the operating system's theme and accent colors (macOS, Windows, Linux).
• Qt Version Consistency: Resolves style differences across various Qt versions.
• Icon Overrides: Allows for overriding old standard Qt default icons.

You can override default theme colors by passing a custom_colors dictionary to qdarktheme.setup_theme(), qdarktheme.load_stylesheet(), or qdarktheme.load_palette().

To apply a color globally across all themes, provide a flat dictionary where keys are color names (e.g., "primary"). To apply colors to a specific theme only, use a nested dictionary where the key is the theme name in brackets, such as "[dark]" or "[light]".

import qdarktheme

# Apply a primary color to all themes
qdarktheme.setup_theme(custom_colors={"primary": "#D0BCFF"})

# Apply a primary color specifically to the dark theme only
qdarktheme.setup_theme(
    custom_colors={
        "[dark]": {
            "primary": "#D0BCFF",
        }
    }
)

To access the latest features and bugfixes, you can install the development version directly from the GitHub repository.

pip install git+https://github.com/5yutan5/PyQtDarkTheme.git@main

To apply the default dark theme to your application, call qdarktheme.setup_theme() after instantiating your QApplication.

Supported theme modes:

• Dark (default): Applies the dark theme.
• Light: Use qdarktheme.setup_theme("light").
• Auto: Use qdarktheme.setup_theme("auto") to sync with the operating system's dark/light mode settings. On macOS, this also syncs with system accent colors.

import sys
from PySide6.QtWidgets import QApplication, QMainWindow, QPushButton
import qdarktheme

app = QApplication(sys.argv)
# Apply the complete dark theme
qdarktheme.setup_theme()

main_win = QMainWindow()
push_button = QPushButton("PyQtDarkTheme!!")
main_win.setCentralWidget(push_button)
main_win.show()

app.exec()

You can manage theme switching in several ways:

1. Automatic Sync with OS: Pass `

import qdarktheme

# Sync with OS
qdarktheme.setup_theme("auto")

# Manual toggle via UI component
combo_box = QComboBox()
combo_box.addItems(qdarktheme.get_themes())
combo_box.currentTextChanged.connect(qdarktheme.setup_theme)

# Manual toggle with pyqtgraph
def toggle_theme(theme) -> None:
    qdarktheme.setup_theme(theme)
    plot_widget.setBackground("k" if theme == "dark" else "w")

To enable HiDPI support, call qdarktheme.enable_hi_dpi().

Important: This function must be called before the instantiation of QApplication.

Note: For Qt6 bindings, HiDPI is enabled by default and this function is not required.

import qdarktheme
import sys
from PySide6.QtWidgets import QApplication

# enable_hi_dpi() must be called before instantiation of QApplication.
qdarktheme.enable_hi_dpi()
app = QApplication(sys.argv)

PyQtDarkTheme uses SVG icons, primarily sourced from Google Material Design Icons.

• Automatic Updates: Icons are automatically downloaded from material-icons and stored in svg/material.
• Adding Icons: To add a new Material Design icon, add the icon name and style to the svg/material_design_icons.json list.
• Warning: Do not edit the svg/material directory manually.

You can install the last released version of pyqtdarktheme using pip. If you need the latest development version, you can install directly from the GitHub repository.

Requirements:

• Python 3.7+
• Qt 5.15+
• PySide6, PyQt6, PyQt5, or PySide2

# Install last released version
pip install pyqtdarktheme

# Install latest development version
pip install git+https://github.com/5yutan5/PyQtDarkTheme.git@main

To apply the flat dark theme to your application, use qdarktheme.setup_theme(). This works with various Qt bindings including PySide6, PyQt6, PySide2, PyQt5, and pyqtgraph.

import qdarktheme
from PySide6.QtWidgets import QApplication, QMainWindow
import sys

app = QApplication(sys.argv)
qdarktheme.setup_theme()

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

Custom SVG icons are located in svg/original. Unlike Material icons, these can be edited manually.

Icon Requirements:

• Use simple SVG code.
• Do not use properties like fill, fill-opacity, or transform, as these are handled by the qdarktheme module internally.

<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M9 16.17 5.53 12.7a.996.996 0 1 0-1.41 1.41l4.18 4.18c.39.39 1.02.39 1.41 0L20.29 7.71a.996.996 0 1 0-1.41-1.41L9 16.17z"/></svg>