Using Qt Resource Files (.qrc) with PyInstaller and PyQt

I built my layout with Qt Designer, so I have a .qrc file that I converted with pyrcc5 to a _rc.py file. Where do I put this file? How do I import or call it? And how do I make sure it's included when packaging my app with PyInstaller?

If you've designed your UI in Qt Designer and added icons, images, or other assets through the resource system, you'll have a .qrc file. To use those resources in your Python application, you need to compile the .qrc file into a Python module, import it, and then make sure it's included when you package your app. Let's walk through the whole process.

What is a .qrc file?

A .qrc file is an XML file that lists the resources (images, icons, etc.) your Qt application uses. Qt Designer creates and references these files when you add images to your UI. Here's a simple example of what a .qrc file looks like:

<RCC>
  <qresource prefix="/">
    <file>icons/logo.png</file>
    <file>icons/save.png</file>
  </qresource>
</RCC>

On its own, this file doesn't do anything in Python. You need to compile it into a Python module that embeds the resource data directly in your code.

Compiling the .qrc file

For PyQt5, you use the pyrcc5 command-line tool:

pyrcc5 resources.qrc -o resources_rc.py

For PyQt6, the pyrcc6 tool no longer exists. PyQt6 dropped support for the Python-based resource compilation. Instead, you can use Qt's own rcc tool to generate a binary resource file, or simply reference your files using standard file paths. See the section below on alternatives for PyQt6.

For PySide6, you use the pyside6-rcc tool:

pyside6-rcc resources.qrc -o resources_rc.py

The output is a .py file containing all your resource data encoded as Python bytes. The filename can be anything, but resources_rc.py is a common convention—and Qt Designer will auto-generate imports using the _rc suffix matching your .qrc filename.

Importing the compiled resource file

Once you have your compiled resources_rc.py file, place it in the same folder as your main application script. Then import it:

1:1 Coaching & Tutoring for your Python GUIs project

60 mins ($195) Book Now

1:1 Python GUIs Coaching & Training

Comprehensive code review • Bugfixes & improvements • Maintainability advice and architecture improvements • Design and usability assessment • Suggestions and tips to expand your knowledge • Packaging and distribution help for Windows, Mac & Linux • Find out more.

import resources_rc

That's it. You don't need to call any functions or use the imported module directly. The act of importing it registers all the embedded resources with Qt's resource system. After the import, any references to resources using the :/ prefix (like :/icons/logo.png) will resolve correctly.

If you're using Qt Designer's generated UI files, they typically include this import automatically at the bottom of the generated Python code. For example, if your .qrc file is called resources.qrc, the generated UI code will contain:

import resources_rc

Make sure the compiled resources_rc.py file is importable from wherever this line runs—usually the same directory is fine.

A complete example

Here's a small working example that loads an icon from the Qt resource system. This assumes you have a resources.qrc file with an icon, compiled to resources_rc.py.

import sys

from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton
from PyQt6.QtGui import QIcon

import resources_rc  # This registers the resources with Qt


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Resource Example")

        button = QPushButton("Click me")
        button.setIcon(QIcon(":/icons/logo.png"))
        self.setCentralWidget(button)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

The QIcon(":/icons/logo.png") path works because import resources_rc registered that path with Qt's internal resource system.

Including resources when packaging with PyInstaller

When you package your application with PyInstaller, the compiled resources_rc.py file needs to be included in the bundle. Since it's a .py file that you import, PyInstaller will usually detect it automatically through its import analysis.

However, if PyInstaller doesn't pick it up (which can happen with dynamic imports or unusual project structures), you have two options:

Option 1: Add it as a hidden import in your .spec file

Open your .spec file and add the module to the hiddenimports list:

a = Analysis(
    ['main.py'],
    pathex=[],
    binaries=[],
    datas=[],
    hiddenimports=['resources_rc'],
    # ... rest of the configuration
)

Option 2: Add it as a data file

You can also explicitly include it in the datas list:

a = Analysis(
    ['main.py'],
    pathex=[],
    binaries=[],
    datas=[('resources_rc.py', '.')],
    hiddenimports=[],
    # ... rest of the configuration
)

After updating your .spec file, rebuild with:

pyinstaller main.spec

The compiled resources_rc.py file contains all your images and icons as embedded data, so you do not need to include the original .qrc file or the original image files in your PyInstaller bundle. Everything is already baked into the Python module.

A common packaging mistake

One easy-to-miss issue: if you forget to include the resources_rc.py file in your bundle, your app will launch but all your icons and images will be missing—often with no obvious error message. If your packaged app is missing icons, check that resources_rc is being imported and that PyInstaller has included it.

You can verify what's in your bundle by checking the build/ directory or by adding a print(resources_rc) statement to confirm the import succeeds at runtime.

Alternatives for PyQt6

PyQt6 removed the pyrcc6 tool. If you're using PyQt6, you have a few options for handling resources:

Use standard file paths

The simplest approach is to skip the resource system entirely and load files directly from the filesystem:

import os
import sys

from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton
from PyQt6.QtGui import QIcon


basedir = os.path.dirname(__file__)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Resource Example")

        button = QPushButton("Click me")
        button.setIcon(QIcon(os.path.join(basedir, "icons", "logo.png")))
        self.setCentralWidget(button)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

Using os.path.dirname(__file__) as a base path ensures your file references work correctly regardless of where the script is run from. When packaging with PyInstaller, add your icons folder to the datas list in your .spec file:

datas=[('icons', 'icons')],

Use PySide6's rcc tool

If you prefer the resource system, you can use PySide6's pyside6-rcc to compile your .qrc file. The output is compatible with PyQt6—both use the same underlying Qt resource system. Just compile with pyside6-rcc and import the resulting file as normal.

Summary

Here's the workflow at a glance:

1. Create your .qrc file (Qt Designer does this for you).
2. Compile it to a .py file using pyrcc5 (PyQt5), pyside6-rcc (PySide6), or skip to filesystem paths (PyQt6).
3. Import the compiled module in your application—just importing it registers the resources.
4. Package with PyInstaller, making sure the compiled resource module is included (usually automatic, but check your .spec file if icons are missing).

The compiled .py file contains everything. You don't need the original .qrc or image files at runtime once the resources are compiled and bundled.