{"id":8572,"library":"qtawesome","title":"QtAwesome","description":"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.","status":"active","version":"1.4.2","language":"en","source_language":"en","source_url":"https://github.com/spyder-ide/qtawesome","tags":["qt","pyqt","pyside","icons","fontawesome","material-design","gui"],"install":[{"cmd":"pip install qtawesome","lang":"bash","label":"Basic Installation"},{"cmd":"pip install qtawesome PyQt5 # or PyQt6, PySide2, PySide6","lang":"bash","label":"Installation with a Qt Binding"}],"dependencies":[{"reason":"Internal abstraction layer for Qt bindings (PyQt5, PyQt6, PySide2, PySide6).","package":"qtpy","optional":false},{"reason":"One of the supported Qt bindings is required to run a Qt application.","package":"PyQt5","optional":true},{"reason":"One of the supported Qt bindings is required to run a Qt application.","package":"PyQt6","optional":true},{"reason":"One of the supported Qt bindings is required to run a Qt application.","package":"PySide2","optional":true},{"reason":"One of the supported Qt bindings is required to run a Qt application.","package":"PySide6","optional":true}],"imports":[{"symbol":"qtawesome","correct":"import qtawesome as qa"}],"quickstart":{"code":"import qtawesome as qa\nfrom qtpy.QtWidgets import QApplication, QLabel\nimport sys\n\napp = QApplication(sys.argv)\n\n# Create a Font Awesome 5 Solid 'home' icon with custom styling\nicon = qa.icon('fa5s.home', color='blue', scale_factor=1.2)\n\n# Create a QLabel and display the icon as a pixmap (e.g., 64x64 pixels)\nlabel = QLabel()\nlabel.setPixmap(icon.pixmap(64, 64))\nlabel.setWindowTitle(\"QtAwesome Icon Example\")\nlabel.show()\n\nsys.exit(app.exec_())","lang":"python","description":"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."},"warnings":[{"fix":"Use icons from 'fa5s', 'fa5r', 'fa5b', 'mdi', 'el', 'fc', 'go', 'ri', 'bi', 'io', 'md' collections. Refer to `qtawesome.icon('fa5s.icon_name')`.","message":"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.","severity":"deprecated","affected_versions":"<=1.1.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.4.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install qtawesome` to install the library.","cause":"The qtawesome package is not installed in your Python environment.","error":"ModuleNotFoundError: No module named '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.","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.","error":"AttributeError: module 'PySide2.QtGui' has no attribute 'QGlyphRun'"},{"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.","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.","error":"Icons not showing up or appearing as blank squares/default system glyphs."}]}