Image inserted in label using Qt Designer does not load from Python

I added an image to a label in Qt Designer, and it shows up fine in the designer, but when I run my application in Python the image doesn't appear. What do I need to do?

If you've used Qt Designer to set an image on a QLabel (or any other widget), you may have noticed that the image displays perfectly inside Designer but is completely missing when you run your Python script. This is a common stumbling block, and the fix is straightforward once you understand how Qt handles bundled assets.

Why the image doesn't appear

When you add an image to a widget in Qt Designer, Designer stores a reference to that image using the Qt Resource System. Instead of a normal file path like images/logo.png, the path looks something like this:

:/images/logo.png

That leading colon (:) tells Qt to look for the file inside a compiled resource bundle, not on the regular filesystem. Designer has its own built-in resource handling, which is why the image shows up there. But when you run your Python application, Qt looks for that same resource bundle at runtime — and if you haven't compiled and imported it, the bundle doesn't exist. The resource path points to nothing, and the image silently fails to load.

The Qt Resource System

The Qt Resource System lets you embed files — images, icons, stylesheets, and more — directly into your application. The files are listed in a .qrc file, which is an XML file that maps resource paths to actual files on disk. A typical .qrc file looks like this:

<RCC>
  <qresource prefix="/">
    <file>images/logo.png</file>
    <file>images/icon.png</file>
  </qresource>
</RCC>

This file tells Qt: "When someone asks for :/images/logo.png, serve the contents of images/logo.png from this bundle."

To make this work in Python, you need to compile the .qrc file into a Python module and then import that module in your application.

Compiling the resource file

The compilation step reads your .qrc file, takes the contents of every file it references, and packages them into a Python file as data. The tool you use depends on which library you're working with.

For PyQt6

Use the rcc tool that comes as part of PyQt6:

pyrcc6 resources.qrc -o resources_rc.py

Note: PyQt6 does not pyrcc6 as a standalone command in all installations. If pyrcc6 is not available, you can use the rcc tool from the Qt installation directly, or consider using PySide6's approach below.

For PySide6

PySide6 includes the pyside6-rcc tool:

pyside6-rcc resources.qrc -o resources_rc.py

Both commands do the same thing: they produce a Python file (here called resources_rc.py) that contains your image data encoded as bytes, along with the registration code that makes those resources available to Qt at runtime.

Importing the compiled resource file

Once you have your resources_rc.py file, you need to import it in your Python application. The import itself is what triggers the resource registration — after the import, all the resource paths (starting with :) become valid.

Add the import near the top of your main script:

import resources_rc

You don't need to call any functions from it or assign it to a variable. The act of importing it is enough.

A complete working example

Let's walk through a full example. Suppose you have a project with this structure:

my_project/
├── images/
│   └── logo.png
├── resources.qrc
├── resources_rc.py   (generated by compiling resources.qrc)
└── main.py

Your resources.qrc file contains:

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

You compile it (using PySide6 as an example):

pyside6-rcc resources.qrc -o resources_rc.py

And here is main.py:

import sys

from PySide6.QtWidgets import QApplication, QLabel, QMainWindow, QVBoxLayout, QWidget
from PySide6.QtGui import QPixmap

import resources_rc  # This registers the bundled resources with Qt


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

        label = QLabel()
        pixmap = QPixmap(":/images/logo.png")
        label.setPixmap(pixmap)
        label.setScaledContents(True)

        layout = QVBoxLayout()
        layout.addWidget(label)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)


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

When you run this, the image loads from the compiled resource bundle and displays in the label — exactly as it appeared in Qt Designer.

Using a .ui file from Designer

If you're loading a .ui file generated by Qt Designer (rather than converting it to Python code), you still need the same import. The .ui file contains the resource path references, and Qt needs the compiled resources to be registered before it tries to resolve them.

For example, if you use QUiLoader (PySide6) or uic.loadUi (PyQt6) to load your .ui file at runtime:

import sys

from PySide6.QtWidgets import QApplication, QMainWindow
from PySide6.QtUiTools import QUiLoader
from PySide6.QtCore import QFile

import resources_rc  # Must be imported before loading the .ui file


app = QApplication(sys.argv)

loader = QUiLoader()
ui_file = QFile("mainwindow.ui")
ui_file.open(QFile.ReadOnly)
window = loader.load(ui_file)
ui_file.close()

window.show()
app.exec()

The import resources_rc line ensures that by the time the .ui file is parsed and Qt encounters :/images/logo.png, the resource is already registered and available.

An alternative: use regular file paths

If you'd prefer to skip the resource system entirely, you can add images to your application using standard file paths instead of resource paths. For example, in your Python code you can load a pixmap directly from a file:

pixmap = QPixmap("images/logo.png")
label.setPixmap(pixmap)

This works as long as the file path is correct relative to where you run your script (or you use an absolute path). The downside is that you need to make sure the image files are distributed alongside your application and that paths stay consistent. The resource system avoids this problem by embedding everything into your Python code.

Summary

When Qt Designer adds an image to a widget, it uses the Qt Resource System with paths that start with :. For those paths to work in your Python application:

1. Create a .qrc file listing your image files (Designer may create this for you).
2. Compile the .qrc file into a Python module using pyside6-rcc or pyrcc6.
3. Import the compiled module in your application before any resource paths are used.

Once you've done these three things, your images will appear in your running application just as they do in Qt Designer. If you're ready to distribute your finished application, see our guide to packaging PySide6 applications with PyInstaller on Windows to ensure your resources are included in the final build.