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.

This project is not affiliated with the Iconify project.

Why

Quick start

Pick the Qt binding your application uses and install the matching extra:

# Install the line that matches the Qt binding you use.
pip install "pyside-iconify[pyside6]"   # you use PySide6 (also the default for type hints)
pip install "pyside-iconify[pyqt6]"     # you use PyQt6
pip install "pyside-iconify[pyqt5]"     # you use PyQt5
pip install "pyside-iconify[pyside2]"   # you use PySide2 (Python 3.10 only)

The extra installs the binding itself plus the type stubs for it. If the binding is already installed, plain pip install pyside-iconify works at runtime too (the library uses whichever binding your program has imported), but without the extra, non-PySide6 users get no precise type hints. See Choosing a Qt binding.

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.

Choosing a Qt binding

The same code runs on four bindings. Import your own binding as usual; the library follows it.

How the binding is picked, in order:

1. The environment variable PYSIDE_ICONIFY_QT_API (pyside6, pyqt6, pyqt5 or pyside2), if set.
2. The binding your program already imported before pyside_iconify.
3. The first installed one, in the order PySide6, PyQt6, PyQt5, PySide2.

Notes:

• Never mix bindings in one process. If your program imported one binding and the environment variable names another, the library raises an error instead of guessing.
• Type hints. The pyqt6, pyqt5 and pyside2 extras also install a small stub package (pyside-iconify-stubs-<binding>) so editors and type checkers see the classes of your binding (QIcon, QSize, ...) instead of Any. Installing it later fixes the hints too.
• Qt5 and HiDPI. Qt5 only produces sharp icons on high-DPI screens when the application sets Qt.AA_UseHighDpiPixmaps before creating the QApplication. Qt6 does this by default.
• PyQt licensing. PyQt5 and PyQt6 are available under the GPL v3 or a commercial license from Riverbank Computing. pyside-iconify itself is MIT and does not bundle Qt or PyQt, but if you choose PyQt, your application is subject to PyQt's license. PySide6 and PySide2 are LGPL.

Support scope

Development

uv sync --extra pyside6 --group test   # once: installs PySide6 and the test tools
uv run pytest -v                       # tests (set QT_QPA_PLATFORM=offscreen first)
uv run examples/smil_showcase.py       # run an example from examples/

The extras are mutually exclusive, so to try another Qt binding use a throwaway environment; your .venv stays on PySide6:

uv run --isolated --extra pyqt6 --group test pytest -v
uv run --isolated --extra pyqt6 examples/smil_showcase.py
# --extra pyqt5, or: --python 3.10 --extra pyside2

The files in examples/ import Qt through a small helper (examples/_qt.py) so that they run on every binding. In your own application, import your binding directly, as in the quick start.

• 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.