QtAwesome

1.4.2 · active · verified Thu Apr 16

QtAwesome is a Python library that provides FontAwesome, Material Design, and other icon fonts for PyQt and PySide applications. It simplifies the integration of scalable vector icons, allowing developers to easily use them in buttons, menus, and other UI elements. The library is actively maintained, currently at version 1.4.2, and receives regular updates, typically every few months, incorporating new features, bug fixes, and improved Qt binding compatibility.

Common errors

```
ModuleNotFoundError: No module named 'qtawesome'
```
cause The qtawesome package is not installed in your Python environment.

fix Run `pip install qtawesome` to install the library.
```
AttributeError: module 'PySide2.QtGui' has no attribute 'QGlyphRun'
```
cause This error typically occurs with older versions of PySide2 which lack the `QGlyphRun` class, an essential component for text and font rendering used by QtAwesome.

fix Update your PySide2 installation to a newer version (e.g., `pip install --upgrade PySide2`) or upgrade `qtawesome` to at least version 1.2.1, which includes a workaround for this specific PySide2 limitation.
```
Icons not showing up or appearing as blank squares/default system glyphs.
```
cause The required icon font files (e.g., Font Awesome, Material Design Icons) are not properly loaded or accessible to the Qt application. This can happen due to failed automatic installation on Windows, corrupted font files, or permission issues.

fix Verify that `qtawesome` is correctly installed. Try restarting your application. If the issue persists on Windows, check system font installations or consider manually installing the fonts. Ensure your `qtawesome` version is recent, especially for Windows font handling improvements.

Warnings

deprecated Font Awesome 4.7 icon set is deprecated and will eventually be removed. While still available, it's recommended to migrate to newer icon sets like Font Awesome 5+ or Material Design.
Fix: Use icons from 'fa5s', 'fa5r', 'fa5b', 'mdi', 'el', 'fc', 'go', 'ri', 'bi', 'io', 'md' collections. Refer to `qtawesome.icon('fa5s.icon_name')`.
gotcha On Windows, QtAwesome attempts to install bundled fonts system-wide or per-user. If the user lacks necessary permissions or if registry keys are missing/unavailable, font installation might fail silently or cause icons not to render correctly.
Fix: Ensure appropriate user permissions for font installation. For persistent issues, manually install the required icon fonts (e.g., Font Awesome, Material Design Icons) into your system's font directory. QtAwesome versions >=1.4.0 include fallback mechanisms and utilities to check bundled font info.
breaking Older versions of QtAwesome (prior to 1.4.1) may exhibit instability or failed test jobs when used with PySide6 or certain PySide2 versions due to specific API differences or caching issues.
Fix: Upgrade to `qtawesome>=1.4.1` for improved compatibility and stability with PySide6 and recent PySide2 versions. Ensure `qtpy` is also up to date.

Install

pip install qtawesome Basic Installation
pip install qtawesome PyQt5 # or PyQt6, PySide2, PySide6 Installation with a Qt Binding

Imports

qtawesome
```
import qtawesome as qa
```

Quickstart

This quickstart demonstrates how to initialize a Qt application, create an icon using `qtawesome`, and display it within a `QLabel`. It uses `qtpy.QtWidgets.QApplication` for compatibility across different Qt bindings.

import qtawesome as qa
from qtpy.QtWidgets import QApplication, QLabel
import sys

app = QApplication(sys.argv)

# Create a Font Awesome 5 Solid 'home' icon with custom styling
icon = qa.icon('fa5s.home', color='blue', scale_factor=1.2)

# Create a QLabel and display the icon as a pixmap (e.g., 64x64 pixels)
label = QLabel()
label.setPixmap(icon.pixmap(64, 64))
label.setWindowTitle("QtAwesome Icon Example")
label.show()

sys.exit(app.exec_())

view raw JSON →