README.md

🚀 Resolving the CustomTkinter iconphoto bug on Windows

1. The Problem

[cite_start]When developing a CustomTkinter application for Windows, attempting to set a custom .ico as the main window icon fails.

Despite verifying the file path is correct, the application continues to display the default CustomTkinter icon in the window's title bar and the taskbar, not the custom icon.

2. The Solution

[cite_start]The root cause of this issue is a combination of how Tkinter/PIL handles image objects and the specific initialization order required by the window manager.

The fix requires three critical steps to be implemented simultaneously:

1. Use PIL (Pillow) to Load: The icon file must be loaded using PIL.ImageTk.PhotoImage. Tkinter's built-in PhotoImage class has poor support for the .ico format, whereas PIL is far more robust.
2. Use the Correct Call Order: You must first call self.wm_iconbitmap() to initialize the window's icon system, and then call self.iconphoto(False, ...) to set the image.
3. Maintain a Persistent Reference: The loaded PhotoImage object must be saved as an instance attribute (e.g., self.icon_image = ...). If it is only stored in a local variable, Python's garbage collector will discard the image after the function completes, causing the icon to revert to default.

3. Code Example (Conceptual)

Place the following logic inside your main application class's __init__ method:

from PIL import Image, ImageTk
import os

# ... inside your __init__ method ...

try:
    # 1. Determine the absolute path to the icon
    script_dir = os.path.dirname(os.path.abspath(__file__))
    icon_path = os.path.join(script_dir, "your_icon_name.ico") # Replace with your icon file

    if os.path.exists(icon_path):
        
        # [cite_start]2. Load with PIL and *maintain the reference* [cite: 1-84]
        self.icon_image_reference = ImageTk.PhotoImage(file=icon_path)
        
        # [cite_start]3. Call in this specific order [cite: 1-84]
        self.wm_iconbitmap() 
        self.iconphoto(False, self.icon_image_reference)
    
    else:
        print(f"Warning: Icon file not found at: {icon_path}")

except Exception as e:
    print(f"Warning: Failed to load icon - {e}")