Using Icons from Qt Resources with PyInstaller

When packaging a PyQt5 or PySide2 application with PyInstaller, you might try to reference your application icon from your Qt Resource (QRC) file. If you've been using QRC files to bundle images and icons into your Python code, it's a reasonable assumption that PyInstaller could access them too. But this leads to a common error:

Unable to open icon file myicon.ico

This short guide explains why this happens and how to fix it.

Qt Resources vs. PyInstaller — Two Separate Worlds

Qt's resource system (.qrc files compiled to Python modules) is a way of embedding files inside your Python code. Once compiled with pyrcc5 or pyside2-rcc, your images and icons become part of a Python module that you import in your application. From within your running PyQt5/PySide2 code, you can then access these resources using the :/ or qrc:/ prefix.

PyInstaller, on the other hand, operates outside your Python application. When you run a command like:

pyinstaller --icon=myicon.ico my_app.py

PyInstaller is looking for myicon.ico as a real file on your filesystem. It doesn't execute your Python code or import your modules at this stage — it's simply reading the .ico file from disk to embed it as the executable's icon in the operating system (e.g., the icon you see in Windows Explorer).

PyInstaller has no knowledge of Qt's resource system. The --icon flag expects a plain file path, not a reference to something inside a compiled QRC module.

The Fix

Keep your .ico file available as a standalone file on disk, even if you've also included it in your .qrc resource file. Then pass the actual file path to PyInstaller:

pyinstaller --icon=path/to/myicon.ico my_app.py

If the icon file is in the same directory where you're running the command, this is simply:

pyinstaller --icon=myicon.ico my_app.py

The QRC file and the PyInstaller --icon flag serve two different purposes:

You'll often want both — the QRC resource for your running application's UI, and the standalone .ico file for PyInstaller to set the executable's icon. There's no conflict in having the same icon in both places.

A Practical Example

Here's what a typical project layout might look like:

my_project/
├── my_app.py
├── myicon.ico          # Standalone file for PyInstaller
├── resources.qrc       # QRC file referencing myicon.ico (for use in your app)
└── resources_rc.py     # Compiled QRC (generated by pyrcc5 or pyside2-rcc)

In your Python code, you use the resource system for the window icon:

import sys

from PyQt5.QtWidgets import QApplication, QMainWindow
from PyQt5.QtGui import QIcon

import resources_rc  # Import the compiled resource module


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("My Application")
        self.setWindowIcon(QIcon(":/myicon.ico"))


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

And when packaging, you point PyInstaller at the real file:

pyinstaller --windowed --icon=myicon.ico my_app.py

Both approaches work together — one sets the icon inside your running application, and the other sets the icon on the packaged .exe file itself.

For complete step-by-step guides on packaging your applications with PyInstaller, see our tutorials for packaging PyQt5 apps on Windows or packaging PyQt5 apps for macOS.

Summary

The Qt Resource system and PyInstaller's --icon flag operate independently. QRC resources are only accessible from within your running Python/Qt application. PyInstaller needs a real file on disk to set the executable's icon. The solution is to keep your .ico file available as a separate file alongside your source code, and pass its path to PyInstaller when you build.

If you're having other issues with icons not appearing after packaging, see our FAQ on Windows icons when packaging with PyInstaller.