pyside-iconify

Give QIcon a data source.

English | 中文 | 日本語 | 한국어 | Español | Français | Deutsch | Русский | Português (BR)

IconWidget("mdi:home", color="red")

One line, one icon. No SVG or PNG files to manage — icons are fetched on demand from the Iconify ecosystem by name and cached automatically. Everything still ends up as a standard QIcon, so it works with any widget that accepts icons.

Status: under active development, not yet published to PyPI. The public API may still change before the first release.

This project is not affiliated with the Iconify project.

Why

Quick start

pip install "pyside-iconify[pyside6]"

from PySide6.QtWidgets import QApplication, QPushButton
from pyside_iconify import IconWidget, get_icon

app = QApplication([])

# A standalone icon widget
icon = IconWidget("mdi:home", size=24, color="red")

# Or hand a standard QIcon to any widget
button = QPushButton("Settings")
button.setIcon(get_icon("mdi:cog", size=20))

app.exec()

That is the whole API for the common case. Icons are downloaded on first use, cached on disk, and rendered locally afterwards.

Highlights

• Theme aware — with no color set, icons follow the widget's text color and switch automatically between light and dark themes; disabled icons fade instead of turning gray (so multi-color icons fade correctly too)
• Full color control — single color, {original: replacement} mapping for multi-color icons, and per-theme overrides (color_light_theme / color_dark_theme)
• Sizes the way you think — numbers, (w, h), QSize, "24px", or "1.5em" (follows the widget's font)
• HiDPI native — sizes are logical pixels; physical pixels are rendered per screen scale factor, no @2x/@3x asset sets
• Loading vs. missing are distinct — loading shows blank, a confirmed miss shows a built-in placeholder and emits failed; optional fallback icon
• QSS friendly — qss="toolbar primary" tags for grouping, style with native setStyleSheet(); priority: parameters → QSS → theme
• Typed and logged — full type hints with py.typed, standard logging (silent by default)

Parameters

Shared by IconWidget and get_icon:

get_icon(name, *, size=24, color=None, color_light_theme=None,
         color_dark_theme=None, selected_color=None, opacity=1.0,
         width=None, height=None, rotate=0, spin=False,
         h_flip=False, v_flip=False)

IconWidget(name, *, ..., hover_color=None, qss=None, parent=None)

Colors accept CSS/SVG names, HEX 3/4/6/8 digit (#RRGGBBAA order), rgb()/rgba()/hsl()/hsla(), tuples, QColor, and Qt.GlobalColor. Unparseable colors raise instead of silently turning black.

Offline packaging

For air-gapped machines or zero-external-dependency builds, pack icons at release time:

python -m pyside_iconify.pack -o icons.json

from pyside_iconify import load_bundle

load_bundle("icons.json")  # at app startup; works inside PyInstaller too

See src/pyside_iconify/pack.py and tests/test_pack_integration.py for the full CLI and API. Local data always takes priority over the network.

Performance

Three-layer cache (icon data → SVG text → rendered bitmaps) with a memory budget, per-frame work kept to a cache lookup and one drawPixmap. A 1000-row QListWidget builds in ~270 ms and scrolls at native speed. For large grids use item views with get_icon; IconWidget is meant for standalone icon slots.

Support scope

Development

uv sync --extra pyside6 --group test
$env:QT_QPA_PLATFORM = "offscreen"
pytest -v

• Contributing guide and release checklist: CONTRIBUTING.md
• Architecture and design decisions: docs/architecture.md
• Roadmap: docs/roadmap.md
• Benchmark: uv run benchmarks/list_scroll.py

License

MIT. Icon collections are subject to their own licenses; Qt is licensed separately by its copyright holders.