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
• Animation built in — spin, pulse, breathe, ping, bounce, plus the self-animating icons of line-md, meteocons and svg-spinners play as-is in IconWidget (SMIL only; see below)
• 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, rotate_overflow=False,
         spin=False, h_flip=False, v_flip=False)

IconWidget(name, *, ..., hover_color=None, animation=None,
           animation_period=None, animation_depth=None, autoplay=True,
           speed=1.0, 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.

Animated icons (SMIL)

Some Iconify sets (line-md, meteocons, svg-spinners, eos-icons, ...) ship icons that animate themselves. IconWidget plays them with no extra code:

IconWidget("line-md:loading-loop", size=48)       # loops
IconWidget("line-md:account")                     # draws itself once, then rests
IconWidget("meteocons:partly-cloudy-day-rain", size=96)

w = IconWidget("line-md:account", autoplay=False, speed=0.5)
w.play(); w.pause(); w.replay(); w.setSpeed(2)
w.isAnimated(), w.isPlaying()

get_icon() and set_icon() return a standard QIcon, which cannot move on its own, so they show the finished state of the animation. Use IconWidget for the animated version. is_animated("line-md:account") tells whether an icon carries an animation (it works without Qt).

Scope: only SMIL is supported (<animate>, <set>, <animateTransform>, <animateMotion> inside the SVG). Other kinds of animation, such as CSS animation, scripts, Lottie or GIF, are not played. An icon that uses a SMIL feature the library does not implement is drawn as a static image of its finished state and a warning is logged once.

Animated frames are cached as bitmaps (trading memory for speed). A long looping icon at a large size can take several MiB of the default 32 MiB cache; raise it with set_cache_limits() if you show many of them at once.

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.