qtawesome: icon fonts such as Font Awesome inside PyQt and PySide

Icons addressed by a prefix and a name

QtAwesome enables iconic fonts such as Font Awesome and Elusive Icons in PyQt and PySide applications. The mechanism is a naming convention rather than a file format. An icon is identified by its prefix and its icon name, separated by a period character, and the prefix tells the library which bundled font to look the glyph up in.

The call is short:

import qtawesome as qta

and the result is an icon object you can hand to a widget. The README example builds buttons for several families in a few lines:

fa6_icon = qta.icon('fa6.flag')
fa6_button = QtWidgets.QPushButton(fa6_icon, 'Font Awesome 6! (regular)')
fa6s_icon = qta.icon('fa6s.flag')
fa6s_button = QtWidgets.QPushButton(fa6s_icon, 'Font Awesome 6! (solid)')

The style is encoded in the prefix itself, which is the detail that matters in practice. fa6 and fa6s are the regular and solid styles of Font Awesome 6, and fa6b selects the brand icons, so the same name such as flag resolves to a different drawing depending on the prefix. The same split appears in the 5.x prefixes, and it continues across the other families.

The library began as a Python port of the QtAwesome C++ library by Rick Blommers, and it is published under the MIT licence. For a Python desktop application, the practical appeal is that a single pip or conda install brings the font data with it, so there is no asset pipeline, no icon font compilation step and no runtime font installation on the user's machine.

Six prefixes, thousands of glyphs, and two Font Awesome generations

The README lists the prefixes that are currently available, and the counts are worth reading closely because they tell you which upstream version of each family is vendored.

Font Awesome is present in two generations. FA 6.7.2 features 2,060 free icons in different styles, split across the fa6 prefix with 163 icons in the regular style, the fa6s prefix with 1402 icons in the solid style, and the fa6b prefix with 495 brand icons. FA 5.15.4 features 1,608 free icons, with fa5 at 151 regular icons, fa5s at 1001 solid icons and fa5b at 456 brand icons.

The other families are single version lines. The ei prefix holds Elusive Icons 2.0 with its 304 icons. The mdi6 prefix holds Material Design Icons 6.9.96 with 6997 icons, while the older mdi prefix holds Material Design Icons 5.9.55 with 5955 icons. The ph prefix holds Phosphor 1.3.0 with 4470 icons, which is 894 icons in five weights each: Thin, Light, Regular, Bold and Fill. The ri prefix holds Remix Icon 2.5.0 with 2271 icons, and msc holds Microsoft's Codicons 0.0.36 with 569 icons.

Two consequences follow. First, the Font Awesome 5 prefixes are kept alive deliberately, which matters for applications that already use fa5 names and cannot afford to re-audit every icon against a new upstream release. Second, every family is pinned to a specific upstream version, so the visual result of a given application is fixed by the qtawesome release it was built against, and a new upstream icon only appears after a package upgrade.

Installing with conda or pip

The installation section offers two routes. With conda:

conda install qtawesome

and with pip, which the README notes is for people who do not have conda installed:

pip install qtawesome

The packaging metadata explains the shape of the dependency. The package requires Python 3.9 or later, declares itself OS independent, and its only install requirement is qtpy, the compatibility layer that lets one codebase talk to PyQt and PySide through the same API. That single dependency is the reason the library can claim to work in both bindings, and it is also the reason a project that already depends on qtpy gains nothing new in weight.

The distribution also ships custom build commands. The setup file registers commands called update_fa6 and update_msc, backed by helper classes in setupbase.py, which are what regenerate the bundled Font Awesome 6 and Codicons data. The repository also carries a RELEASE.md, an UPDATE.md, a CHANGELOG.md and a SECURITY.md, so the process of updating the vendored icon sets is a documented part of the project rather than something that happens silently.

For a first use, the shortest useful path is to install the package, import qtawesome, and pass the result of qta.icon to a widget. The example file at the top level of the repository and the documentation published at qtawesome.readthedocs.io cover the rest.

Styling, alpha channels and stacked glyphs

Beyond a plain icon, the API carries the options that a designer would otherwise reimplement. The first is state styling, where an active variant can be swapped in and both colours given:

styling_icon = qta.icon('fa5s.music',
                        active='fa5s.balance-scale',
                        color='blue',
                        color_active='orange')

The second is transparency, where the colour is passed as a tuple with an alpha value, and the README notes that alpha must be a number between 0 and 255:

icon_with_alpha = qta.icon('mdi.heart',
                           color=('red', 120))

The third is stacking, which composes several glyphs into one icon using the options list, with a scale factor and a per layer colour:

camera_ban = qta.icon('fa5s.camera', 'fa5s.ban',
                      options=[{'scale_factor': 0.5,
                                'active': 'fa5s.balance-scale'},
                               {'color': 'red'}])

These are the features that make the library more than a name lookup, and they are also the features that tie it to a font based rendering model rather than to a set of image files. A scale factor and a per layer colour work because the glyph is drawn as text, and the drawing mode is selectable: text is the default for icons without animation, path is the default for icons with animations, and glyphrun and image are also available:

drawn_image_icon = qta.icon('ri.truck-fill',
                            options=[{'draw': 'image'}])

That last choice is the escape hatch. Rendering as an image produces a static picture rather than a live glyph, which is what you want when the icon has to survive a setting that does not support font rendering, and it is also how a spinning or animated icon is handled, since the animated family gets the path mode by default.

Bundled fonts mean pinned icons and a larger install

The design decision with the widest consequences is that the icon fonts are shipped inside the package rather than downloaded at runtime. That is what makes the install work offline and what makes the icon set identical on every machine, and it is also the source of the main trade-off.

A user of a newer upstream icon set than the one bundled has three options. Wait for a qtawesome release that includes it, patch the bundled data locally, or switch to a different mechanism for that one icon. There is no runtime fetch in the design, so the upgrade path runs through the package manager, which is exactly what the update_fa6 and update_msc build commands in the packaging are for.

The size of that data shows up in the install. The counts in the README are thousands of glyphs across six families and two Font Awesome generations, and the repository includes a browser tool, a screenshot and a bundled binary tree for the fonts. For a desktop application that is usually irrelevant. For a small utility distributed as a Python package, or a frozen application, it is a real number on your download.

A second constraint is the Python floor. The package requires Python 3.9 or later and its classifiers list Python 3.9 through 3.13. The last push was on 2026-08-31 and the most recent release is 1.4.2, published on 2026-04-10, after 1.4.1 in January 2026 and 1.4.0 in February 2025, so the project is moving but on a slowish release rhythm.

The licence is MIT, and the copyright line in the README is held by the Spyder Project Contributors, which matters if you redistribute an application that embeds these font files.

Where qtawesome is the wrong choice

Three situations argue against it.

First, custom artwork. Font based icons cover a large catalogue of common symbols, but they do not cover a product's own logo, a diagram or a bespoke glyph set. Drawing those means bringing a different mechanism into the application, and at that point the application has two icon systems instead of one.

Second, an application that needs an icon to look identical everywhere regardless of the platform's font support. The drawing mode options address part of this, since the image mode produces a static rendering, but the fundamental coupling to a font file remains.

Third, a project that is not a PyQt or PySide application. The single install requirement is qtpy, the compatibility layer for the Qt Python bindings, so a non-Qt project gets a Qt dependency it does not otherwise need. A non-Qt application is better served by whatever icon handling its own toolkit provides, or by shipping SVG assets and letting the application load them.

The alternative worth weighing is the C++ QtAwesome library that this project was ported from, for a team whose application is written in C++ rather than Python. The difference in approach is the language binding and the packaging: the C++ library is integrated into a C++ build with the fonts as resources, while the Python port installs from a wheel or a conda package and hides the same kind of data behind a Python API. For a Python desktop application, the port is the cheaper option by a wide margin, and for a C++ application it is not an option at all.

Editorial conclusion

qtawesome is the right choice for a PyQt or PySide application that wants a large, consistent icon set without shipping artwork or writing a build step, particularly where a toolbar of a few dozen glyphs is all you need. It is the wrong choice for a project that needs custom vector artwork, that wants icon updates without a package upgrade, or that would rather depend on SVG files and Qt's own icon handling than on bundled font files. Before you adopt it, decide whether the bundled icon versions match what your design calls for, check that your Qt binding is covered by qtpy, and confirm the icon name you want exists in the prefix you plan to use.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. spyder-ide/qtawesome on GitHub