qt-resources

Qt Resource System

.qrc File Format

<!-- resources/resources.qrc -->
<!DOCTYPE RCC>
<RCC version="1.0">
  <qresource prefix="/icons">
    <file alias="app.png">icons/app.png</file>
    <file alias="save.svg">icons/save.svg</file>
    <file alias="open.svg">icons/open.svg</file>
  </qresource>
  <qresource prefix="/themes">
    <file>dark.qss</file>
    <file>light.qss</file>
  </qresource>
  <qresource prefix="/data">
    <file>default_config.json</file>
  </qresource>
</RCC>

File paths in .qrc are relative to the .qrc file's location. The alias attribute sets the name used at runtime.

Compiling Resources (Python)

PySide6:

pyside6-rcc resources/resources.qrc -o src/myapp/resources/rc_resources.py

PyQt6:

pyrcc6 resources/resources.qrc -o src/myapp/resources/rc_resources.py

Add to pyproject.toml build scripts or a Makefile to keep in sync. The compiled file imports cleanly:

# src/myapp/resources/__init__.py
from . import rc_resources  # noqa: F401 — side-effect import registers resources

Import rc_resources before any code that uses :/ paths. The module-level import in resources/__init__.py is the cleanest approach — it runs once when the package is first imported.

Using Resources at Runtime

from PySide6.QtGui import QIcon, QPixmap

# Icons
icon = QIcon(":/icons/save.svg")
button.setIcon(icon)
button.setIconSize(QSize(16, 16))

# Pixmaps
pixmap = QPixmap(":/icons/app.png")
label.setPixmap(pixmap.scaled(64, 64, Qt.AspectRatioMode.KeepAspectRatio))

# Text files (themes, config)
from PySide6.QtCore import QFile, QTextStream

file = QFile(":/themes/dark.qss")
if file.open(QFile.OpenModeFlag.ReadOnly | QFile.OpenModeFlag.Text):
    stream = QTextStream(file)
    stylesheet = stream.readAll()
    file.close()

Inline Resource Loading (No Compile Step)

For small assets during development, embed directly:

import base64
from PySide6.QtGui import QIcon, QPixmap
from PySide6.QtCore import QByteArray

def icon_from_base64(data: str) -> QIcon:
    b = QByteArray.fromBase64(data.encode())
    pix = QPixmap()
    pix.loadFromData(b)
    return QIcon(pix)

SVG Icons

SVGs are the preferred format — they scale perfectly at all DPIs:

from PySide6.QtSvgWidgets import QSvgWidget
from PySide6.QtGui import QIcon

# In a layout
svg = QSvgWidget(":/icons/logo.svg")
svg.setFixedSize(48, 48)

# As window icon (QIcon handles SVG natively on most platforms)
self.setWindowIcon(QIcon(":/icons/app.svg"))

High-DPI (Retina/4K) Support

# In main() — before QApplication
os.environ["QT_ENABLE_HIGHDPI_SCALING"] = "1"

app = QApplication(sys.argv)
app.setHighDpiScaleFactorRoundingPolicy(
    Qt.HighDpiScaleFactorRoundingPolicy.PassThrough
)

Use SVG icons wherever possible. For raster icons, provide @2x variants:

<qresource prefix="/icons">
  <file alias="save.png">icons/save.png</file>
  <file alias="save@2x.png">icons/save@2x.png</file>
</qresource>

Qt automatically selects @2x variants on high-DPI displays.

Project Automation

Add resource compilation to your build process:

# pyproject.toml — using hatch
[tool.hatch.build.hooks.custom]
path = "build_hooks.py"

# build_hooks.py
import subprocess
from pathlib import Path

def build_editable(config, ...):
    subprocess.run([
        "pyside6-rcc",
        "resources/resources.qrc",
        "-o", "src/myapp/resources/rc_resources.py"
    ], check=True)

Or a simple Makefile target:

resources: resources/resources.qrc
	pyside6-rcc $< -o src/myapp/resources/rc_resources.py