Packaging with Pyinstaller [improved wiki]

[Akascape]

Packaging

When you are creating an executable with pyinstaller, then there are some things you have to consider. It is recommended to use Auto-py-to-exe which is an easy interface for pyinstaller.

One-Dir or One-File?

First add your main python program in the script location option.
Then you will have to choose between two options: One Directory and One File.

Packaging with one-directory:

This mode will give a folder where you will get lots of files including the exe. The main benefit of using one-dir is that you will get a faster loading executable with all the folders in one place.
But the problem is that the folder looks ugly with so many files, you may have to use some exe-installer/setup creater.

(If you are using this mode, then skip the one-file part)

Packaging with one-file:

With this mode, you will get a single executable file. When you run that executable, a temp folder (named as _MEIPASS...), will be created in a OS defined temp location where it will extract all the necessary files that we used to get with the one-dir mode. This unpacking is done every time when you open that executable which affects the startup time. This is how the one-file mode works.

Packing external files with one-file mode:

Generally, if you are using any external assets like images, sub-folders or any other files, then you will need to keep that asset outside the one-exe file.

But if you want to pack those assets/folders inside that one-exe file, then you will have to do a little tweak in your program.
To do this, you have to first add those assets/folders under the additional files option of pyinstaller.

Then you will have to change the search method for all assets in your program:

# Just add this search function:
import sys, os
def resource(relative_path):
    base_path = getattr(
        sys,
        '_MEIPASS',
        os.path.dirname(os.path.abspath(__file__)))
    return os.path.join(base_path, relative_path)

# Then use this function to find the asset, eg: resource("my_file")

If you are importing an asset like this:

image = "CustomTkinter_logo.png"

Then change it to this:

image = resource("CustomTkinter_logo.png")

_Note: Make sure that the file paths are relative, avoid uses of slash, instead use os.path.join method _

We are doing this because the one-file exe unpacks its files in a separate temp directory when it is executed. So, you have to use this method to search the packed files within that hidden temp folder.

If you want to reduce the size of one-file exe, then here is a pro-tip: #939 (comment)

Another pro tip if you want to change the default temp dir location: #939 (comment)

Console Window

Under this section, you will get two options: console-based and window-based.
Console-Based: You will get a console window running in the background with your main app.
However there is new option to hide/minimize the console automatically after startup, see pyinstaller/pyinstaller#7735 (write the code in additional arguments section)

Window-Based: You will only get the app window. (recommended for most applications)

Icon

Under the icon section, you can set the icon for your app. (Just add your .ico file)
Note that this icon will not be shown inside the application titlebar.
To pack the custom icons read the next heading.

Additional Files and Folders

You can add all other assets/folders/modules accordingly with pyinstaller

You will have to add the folder customtkinter because pyinstaller doesn't automatically include datafiles like .json from the library.

You can find the install location of the customtkinter library with the following command:

pip show customtkinter

A location will be shown in the details, for example: c:\users\<user_name>\appdata\local\programs\python\python310\lib\site-packages, where you will find the customtkinter package.

Similarly, for any other module import error, try to pack them separately like this.

For easier access, it is recommended to keep a copy of the module folders like customtkinter in the same directory where your python program is present.

Output

There are many other advanced options you can tweak if you research more about pyinstaller, like adding a splash screen image and runtime hooks.

Otherwise just move to the Settings section and choose your Output Directory where the executable will be created.
Then just click on Convert!

That's all you need to know about packaging your customtkinter app to an executable file with pyinstaller.

Full Video guide:

[sathyarajshetigar]

Hi, I have one config.yml which user can edit and I want to ship it along with the exe and not inside the temp folder. Can you show how to achieve this? If I add config.yml it gets bundled with the exe. I want it to be outside exe and should be readable from exe

[sathyarajshetigar]

Awesome. Thanks for the assist @Akascape

[Akascape]

I want it to be outside exe and should be readable from exe

@sathyarajshetigar
You don't need to add resource or pack that file/folder. just search it as usual:

config_file = "outside_folder//config.yml" # config.yml is a file inside a folder, make sure that folder is outside the exe

But still, there are some better methods too:

Method-1

DIRPATH = os.getcwd() 
# now search the file outside exe like this:
config_file = DIRPATH+"//outside_folder//config.yml"

With this method, you can search the files/folders outside exe. (works only inside the main program)

Method-2

if getattr(sys, 'frozen', False):
    DIRPATH = os.path.dirname(sys.executable)
    sys.path.append(DIRPATH) 
    config_file = DIRPATH+"//outside_folder//config.yml"

With method 2 you can properly search any file/folder, even if it is a module or sub file.
Tip: If there is a heavy module, then place that module folder outside the exe and write that module name under exclude-module in pyinstaller [advanced] so that it doesn't get packed. Benefit: faster loading time of the one-exe.

[avalon60]

Hi, I have one config.yml which user can edit and I want to ship it along with the exe and not inside the temp folder. Can you show how to achieve this? If I add config.yml it gets bundled with the exe. I want it to be outside exe and should be readable from exe

It's a long time, since I used Pyinstaller, and I think I used the one file option. The limitation here is that each time you invoke the EXE, you will get a new instance of your program. This means that edits of anything by the user won't persist.
To get around this, you'd need to have the exe, do some kind of install, of your program, or copy the file to a predetermined location, where it can be found the next time the EXE is launched.

[ghost]

So a config file. I've done something similar with my project dishb/hive.
If we assume the current working directory is the top-level directory, then the config file is stored at ./config/settings.cfg.
Whenever my app is launched, the settings are read from that file (inside the bundled exe/app file) and loaded.

[coolcoder613eb]

nuitka?

[VollGerne]

With following configuration you can deploy your app as 'onefile' or 'onedirectory' option, both options work fine.

[coolcoder613eb]

for nuitka on windows: ``` nuitka file.py --standalone --onefile --disable-console --include-package-data=customtkinter --enable-plugin=tk-inter ``` works, and on linux(where you have the customtkinter folder in the current directory), ``` python3 -m nuitka file.py --standalone --onefile --include-package-data=customtkinter --enable-plugin=tk-inter --include-data-dir=./customtkinter=./customtkinter ```

[coolcoder613eb]

the markdown isn't rendering?

[Wolf-SO]

Below the verbatim copy of the rendered post by @coolcoder613eb

for nuitka on windows:

nuitka file.py --standalone --onefile --disable-console --include-package-data=customtkinter --enable-plugin=tk-inter

works,
and on linux(where you have the customtkinter folder in the current
directory),

python3 -m nuitka file.py --standalone --onefile --include-package-data=customtkinter --enable-plugin=tk-inter --include-data-dir=./customtkinter=./customtkinter

[unknown-kel]

how about adding data like images used in the script and also setting the icon, when i tried it the compilation was successful but the file didnt open at all

any solution?

[sathyarajshetigar]

Thanks. Can you please show how to include yml files and icon files as well

[siddheshgunjal]

If you're using tkcalendar inside CTk UI then you'll have to add follwing --hidden-import in the advanced option in auto-py-to-exe

This is because pyinstaller does not include babel libraries by default. We have to manually import them while packaging.

[Akascape]

Another pro tip for one-file mode:

Sometimes you may have large libraries and modules included in the one-exe file which results in slower startup time.

In that case you can exclude some module folders outside the main exe file with some tweaks:

Here is how you can do it:

• Make a folder Modules in the same directory where main program is present.
• Copy and paste all the heavy modules inside that folder.
• Add this search path function inside your main program:

# add this code in the top (before imports)
import sys, os
if getattr(sys, 'frozen', False):
    app_path = os.path.join(os.path.dirname(sys.executable), "Modules")
    sys.path.append(app_path) # search this path for modules

• Under advanced pyinstaller option --exclude-module, write the names of all those modules you excluded in that module folder.

This will reduce the startup time and size of the executable

[RunsOnRum]

Can you elaborate on the usage? For instance with I have from PIL import Image but I include --add-data for the PIL library folder, can I exclude the parts of PIL that I do not require?

[Akascape]

@RunsOnRum

For instance with I have from PIL import Image but I include --add-data for the PIL library folder,

PIL library is automatically packed, so you don't have to include it with --add-data.

can I exclude the parts of PIL that I do not require?

No, it can't be excluded in parts like that, you either have to pack the full folder or delete the unwanted files from the module manually.

Moreover PIL is not a heavy module, so it will not make a huge difference if you exclude it.

This exclude method is only good for heavy modules like opencv, imageio-ffmpeg, avlibs etc. (where size>50mb)

[RunsOnRum]

Thank you for the clarification. It is very much appreciated!

[ghost]

please i'm using cx_freeze to package my python script how do i include the path of the customtkinter

import sys
from cx_Freeze import setup, Executable

"""Copyright (c) 2023 Kennart Tech"""

---------------------------------------------------------------------

build_exe_options = {
"packages": ["tkinter", 'ttkthemes', 'customtkinter'], # List of packages to include
"excludes": ['flask'], # List of packages to exclude
"include_files": ['icons/'], # List of files to include
"include_msvcr": True, # This include Microsoft Visual C++ runtime
"optimize": 2, #These increase the speed of the software in terms of the perfomance
"zip_include_packages": ['icons/tools'],
# "zip_exclude_packages": [],
# "zip_exclude_dlls": [],
}

----------------------------------------------------------------------

------------------------------------------------------------------

shortcut_table = [#This defines the shorcut to be created for the frozen executable
("DesktopShortcut", # Shortcut
"DesktopFolder", # Directory_
"Modern Calculator", # Desktop icon Name
"TARGETDIR", # Component_
"[TARGETDIR]CALCULATOR.exe", # Target
None, # Arguments
None, # Description
None, # Hotkey
None, # Icon
None, # IconIndex
None, # ShowCmd
"TARGETDIR", # WkDir
),
]

msi_data = {"Shortcut": shortcut_table}

------------------------------------------------------------------

-----------------------------------------------------------------

base = None #this will set the base of the application to a GUI application on Windows.
if sys.platform == "win32":
base = "Win32GUI"

------------------------------------------------------------------

------------------------------------------------------------------------

script_path = "CALCULATOR.py" # Replace with the path to your Python script

------------------------------------------------------------------------

-----------------------------------------------------------------------

setup(
name="Modern Calculator",
version="1.0",
description="My Python script",
options={
"build_exe": build_exe_options,
"bdist_msi": {"data": msi_data},
},
executables=[Executable(script_path, base=base, icon="icons/logo.ico", shortcut_name="main")],
author="K-Tech Software",
)

----------------------------------------------------------------------------

[Akascape]

@kennarttech Just put the path of customtkinter under include_files:

"include_files": ['icons/', 'customtkinter/']

[sathyarajshetigar]

Did anyone explore the codon compiler?

[Akascape]

Nah bro, have to try it. I don't know if it will work with big projects.

[Akascape]

Pro-Tip for one-file mode:

Generally the temp folder for one file mode (named like MEIxxxxxx) is extracted in an OS defined temp location. But sometimes, if your app crashes or closed forcefully, then the temp dir is not removed automatically which can lead to c-drive storage issues.
Moreover, many basic users don't know the default os temp location.

But there is an option for the one-file mode in which the temp folder spawn location can be changed.

Under Advanced tab there is an option called --runtime-tmpdir, you can just write "temp" in that field.

Now, the temp folder will be extracted in the same directory where the exe is present (inside a new 'temp' dir).

In this case, users can easily find and delete that temp folder if the app crashes. So, it is just good for the user side specially if your app is in experimental stage.

Disadvantage: The app will not open if the user runs the exe inside any read-only location having no access to write.

[OneBigLotus]

I'm brand new to all this, and I've found both the ofifcial wiki and this improved wiki very helpful and informative.
I just tried my hand at this for the last 4 hours and after converting my paths and including all of my folders, I've reached this error that seems to be coming from customtkinter itself, and I'm not really able to find a fix for it.
it's happening when ctkinter tried to get the system appearance.

I do have darkdetect added to the source folder

[Akascape]

@OneBigLotus

I guess your pyinstaller packed an older version of customtkinter. This may happen due to different python-version installed.

The best way to fix this:
copy the latest customtkinter folder to the directory where your program is also present. Try running your program again after pasting it to make sure that you have pasted the correct module.

Then do the pyinstaller setup again.
Pyinstaller will now pack that new copied version of customtkinter. Also add that folder under additional options.

[OneBigLotus]

will do, the program was written back in September, and updating customtkinter seems to break it. I'll see what I can do to fix it.

[OneBigLotus]

update for anyone in this thread, I've since finished the application with the newest version of customtkinter, and it's all great

[sathyarajshetigar]

with nuitka you guys noticed any performance improvements?

[sathyarajshetigar]

Anyone

[alfmelchor]

@Akascape Thank you for the updated documentation! Does this tutorial work for macOS? I'm hoping to get guided through the process if that's not too much to ask!

[Akascape]

@alfmelchor
Don't know if all options of pyinstaller will work or not.
But there is py2app which is more mac os oriented, you can use that.

You can easily create an executable if you know the proper debugging with these tools.

[alfmelchor]

I was able to package my application, but when I tried to open it, it immediately closed (using auto-py-to-exe). I wanted to reformat my entire project in order to use your suggested one-file packaging but ran into issues as well. I have my source code on https://github.com/alfmelchor/StudyAid

Thanks for the reply. I'll look into using py2app and see how it goes!

[alfmelchor]

@Akascape I'm running into an issue when opening the finished app.

Traceback (most recent call last):
File "/Users/alfonsomelchor/Desktop/source/dist/main.app/Contents/Resources/boot.py", line 522, in
_run()
File "/Users/alfonsomelchor/Desktop/source/dist/main.app/Contents/Resources/boot.py", line 394, in _run
exec(compile(source, path, "exec"), globals(), globals())
File "/Users/alfonsomelchor/Desktop/source/dist/main.app/Contents/Resources/main.py", line 1, in
import customtkinter as ctk
File "/Users/alfonsomelchor/Desktop/source/dist/main.app/Contents/Resources/lib/python3.11/customtkinter/init.py", line 5, in
from tkinter import Variable, StringVar, IntVar, DoubleVar, BooleanVar
File "tkinter/init.pyc", line 38, in
ModuleNotFoundError: No module named '_tkinter'
2023-05-13 10:15:41.831 main[2223:39553] Launch error
2023-05-13 10:15:41.831 main[2223:39553] Launch error
See the py2app website for debugging launch issues

[Akascape]

@alfmelchor Try the solutions given here: https://stackoverflow.com/questions/15403205/py2app-problems

[alfmelchor]

Thanks for your help! I was able to successfully package it! :)

[B16f00t]

I have no problems compiling normally, but I noticed that CTkSwitch and CTkScrollableFrame, show an error when creating onefile.
I would like to know if anyone has encountered this problem and if you have been able to solve it.
Regarding CTkSwitch, I perceive that the error could be 'fg_Color'.

self.conf_switch_update = customtkinter.CTkSwitch(master=self.conf_general_frame, text="",
File "customtkinterwindows_widgets_ctk_switch.py", line 57, in __init__
self._fg_color = ThemeManager.theme["CTkSwitch"]["fg_Color"] if fg_color is None else self._check_color_type(fg_color)
KeyError: 'fg_color')

And from 'CTkScrollableFrame', it shows me:

Error: 'CTkScrollableFrame'.

[Akascape]

@B16f00t
I guess your pyinstaller is packing the wrong version of ctk. (probably less than v5)

Download the latest version from the repo and paste the customtkinter folder in the same directory where your program is present. Also pack that folder inside the additional folders of pyinstaller.

[B16f00t]

Thank you very much,
I had updated the library using 'pip' but I didn't have updated the folder contents, I had an older version that It was used when compiling.

[Akascape]

Full Video guide:

Link: https://youtu.be/6WApXONjGFA

[zSynctic]

After formatting my pc, I get this issue when packaging for some reason when it was working before. FileNotFoundError: [Errno 2] No such file or directory: 'C:\Users\...\AppData\Local\Temp\_MEI118322\../Assets/icon.ico'

[Akascape]

@zSynctic The resource thing will get you to this path: C:\Users...\AppData\Local\Temp_MEI118322
After that it joins the asset location.
But you should also pack the asset properly so that is search in the _MEI folder. Go in the location while opening the app and see if the asset files are properly there or not. Must be some relative location issue.

[zSynctic]

The assets folder is actually there and the images and icon are there but for some reason it still doesn't work

[zSynctic]

Anyway to fix?

[Akascape]

@zSynctic Check your search method again:

Keep this in mind:
Don't use slashes in the path string, instead use os.path.join method.

All you can do is debug like this;

In your application, print the path variable:
print(resource(os.path.join("assets","logo.ico")))

Then check this path in the _MEI folder. I am guessing its all because you are using wrong slashes in the path string.

[zSynctic]

Thanks I managed to make small changes for it to work with your snippet.