Skip to main content

Packaging

You can turn a CustomTkinter app into a standalone program with PyInstaller. Current versions of PyInstaller know CustomTkinter and automatically include its theme and font files, so you no longer have to add the library folder by hand. Both --onedir and --onefile work.

PyInstaller​

Install or update PyInstaller in the same environment as your app:

pip install --upgrade pyinstaller

Then build your app:

pyinstaller --noconfirm --onedir --windowed "<Path to Python Script>"
  • --onedir (default) creates a folder with the executable and all files it needs. The app starts quickly.
  • --onefile creates a single executable. It is easier to share, but starts a bit slower because it unpacks itself first.
  • --windowed hides the console window on Windows and creates an .app bundle on macOS.

The result is in the dist folder. PyInstaller builds for the operating system it runs on, so build on Windows for Windows, on macOS for macOS and on Linux for Linux.

Tested setup

CustomTkinter 6.0.0 with PyInstaller 6.22 and the --onefile option, without any extra arguments. The theme and font files are included by the CustomTkinter hook in pyinstaller-hooks-contrib, which is installed together with PyInstaller.

Older PyInstaller versions​

If you are on an old PyInstaller version and the packaged app can't find the theme files, either update PyInstaller or add the CustomTkinter data files explicitly:

pyinstaller --noconfirm --onedir --windowed --collect-data customtkinter "<Path to Python Script>"

Your own data files​

Images, icons or your own theme .json files are not included automatically. Add them with --add-data:

pyinstaller --noconfirm --onefile --windowed --add-data "my_theme.json:." --add-data "images:images" "<Path to Python Script>"

In the app, load these files relative to the location of the program, not relative to the current working directory:

import os
import sys

def resource_path(relative_path):
# PyInstaller unpacks the files to sys._MEIPASS, during development use the script folder
base_path = getattr(sys, "_MEIPASS", os.path.dirname(os.path.abspath(__file__)))
return os.path.join(base_path, relative_path)

customtkinter.set_default_color_theme(resource_path("my_theme.json"))

Images with CTkImage​

If your app uses CTkImage or other parts of Pillow, the packaged app can crash with ModuleNotFoundError: No module named 'PIL._tkinter_finder', because Pillow loads this module in a way that PyInstaller doesn't detect. Add it as a hidden import:

pyinstaller --noconfirm --onedir --windowed --hidden-import PIL._tkinter_finder "<Path to Python Script>"

A complete example with images, an icon, --onedir and --onefile is in the tutorial Packaging with PyInstaller.

Auto Py to Exe​

Auto Py to Exe is a graphical interface for PyInstaller. Choose your script, select "One Directory" or "One File" and "Window Based", and add your own data files under "Additional Files". The CustomTkinter folder does not need to be added anymore.