Packaging an app and its icon when using Python

Hi!

I am trying to use imgui_bundle to develop a Python-based desktop app for computer graphics. The first thing I tried was setting a custom icon for the window, but I had no luck.

I put my icon at assets/app_settings/icon.png as required in readme, but it won't show up. I tried different files that match the specs (256px), but nothing worked.

My env:

Windows 11
Python 3.13.1
imgui-bundle 1.92.5
uv 0.9.5

You can find repo here: https://github.com/jakerdy/imgui_bundle_noicon.git

There were no errors printed in the terminal; the icon simply won't show up.

Ok, I found a hack. You could put your custom icon into site_packages of venv. But what is an intended way of changing icon in python based apps?

@jakerdy

Hi @jakerdy,

Thanks for reporting this!

First, there are two things you need to know.

C++ vs Python:
In C++, Hello ImGui and ImGui Bundle can provide icons for applications' exe files. When using Python, the icon is linked to the Python executable itself. You need a packaging tool (such as PyInstaller, for example) to override Python's icon.

Window icon versus App icon

There are two different types of icons:

Window icon: The icon shown in the window title bar and taskbar while the app is running (works only on Windows and Linux, not available on macOS)
App icon: The icon of the executable/application file itself (shown in file explorers, app launchers, etc.). On macOS, this will also be the window icon.

Current Support in Python

Window Icon (Windows & Linux only):
With Python, assets/app_settings/icon.png should define the window icon on platforms that support this (Windows and Linux, but not macOS). However, you need to:

Set the assets folder correctly at the start of your application:

from imgui_bundle import hello_imgui, immapp
import os

def main():
    # Set assets folder - adjust path to your setup
    assets_path = os. path.join(os.path. dirname(__file__), "assets")
    hello_imgui.set_assets_folder(assets_path)
    
    # Your app code... 
    immapp. run(...)

if __name__ == "__main__": 
    main()

Icon specifications: Make sure your icon.png is:
- Square
- At least 256×256 pixels (512×512 is preferred)
- Located at <your_assets_folder>/app_settings/icon.png

App Icon (Packaged Applications):
The automatic icon.png conversion from assets/app_settings/icon. png is currently a C++ only feature (it requires CMake during build).

For Python applications, you need to use packaging tools like PyInstaller to set the application icon when creating standalone executables.

Packaging Your Python App with Custom Icon

ImGui Bundle provides examples for packaging Python applications with PyInstaller:

Demo & Documentation:

For Windows with PyInstaller, you would create a spec file like this:

# yourapp.spec
a = Analysis(
    ['your_app.py'],
    datas=[("assets", "assets")],  # Include assets folder
    # ... other settings
)

exe = EXE(
    pyz,
    a.scripts,
    # ... other settings
    icon='path/to/your_icon.ico',  # <-- Set app icon here (Windows uses . ico)
)

Then build with:

pip install pyinstaller
pyinstaller yourapp.spec

Summary

Development: The window icon from assets/app_settings/icon.png should work if you call hello_imgui.set_assets_folder() correctly
Distribution: For the app icon (executable icon), you need to use PyInstaller or similar packaging tools with their icon settings
C++ vs Python: The automatic icon conversion is a C++ build-time feature; Python apps need packaging tools for app icons

I hope this clarifies things! Let me know if you need more help.

Disclaimer: this answer was based on a reply by github copilot which I did proof-read and reword.

Thank you very much for such a detailed answer!

It's a great fit for the docs. Yep, I've been digging into the source code for the last couple of days and asking GPT-5.2 (it knows how your library works pretty well). So now I know now. Going to check pyinstaller...

Also, I was struggled a bit with immapp vs hello_imgui. It would be great to write some top level overview of modules available in a lib and their primary function.

So far, this is the best ImGui "bundle" that just works, and it comes with multiple packs of batteries included, not just one :)

reopen as faq

Closing this to keep the open issues for open problems.
The answer stays here, and all the FAQ answers are listed here:
https://github.com/pthom/imgui_bundle/issues?q=is%3Aissue+label%3AFAQ

Navigation Menu

Repository navigation

Packaging an app and its icon when using Python #427

Current Support in Python

Packaging Your Python App with Custom Icon

Summary

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Packaging an app and its icon when using Python #427

Description

Activity

jakerdy commented on Dec 25, 2025

pthom commented on Dec 27, 2025

Current Support in Python

Packaging Your Python App with Custom Icon

Summary

jakerdy commented on Dec 27, 2025

pthom commented on Dec 27, 2025

pthom commented on Oct 21, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions