Frequently Asked Questions¶

Problems with running frozen programs¶

A common problem is that cx_Freeze hasn’t automatically detected that a file needs to be copied. Modules that your code imports are detected, but if they’re dynamically loaded - e.g. by a plugin system - you have to tell cx_Freeze about them. This is easy using a Setup script:

For Python code, specify the module names in the includes or packages options.
List the module’s compiled libraries (.dll or .so files) in the include_files option.
Use bin_includes to include dependencies of binary files that would normally be excluded (common use is to include “libffi.so”).
Data files are a bit more complex - see Using data files.

Problems with freezing programs¶

To determine which packages need to be copied with your application, cx_Freeze follows the imports. If your installation contains a lot of packages, this may lead to undesired behavior, such as cx_Freeze encountering a recursion error when trying to compute the list of dependencies, or the lib folder of the frozen application containing many unnecessary packages. In this case, use cx_Freeze in a virtualenv. Alternatively, the setup_script also offers the excludes option to explicitly exclude dependencies that would otherwise be included.

Specifying modules and packages¶

The definitions of modules and packages are different. See Python documentation.

Modules .
Packages .

Windows command prompt appears briefly¶

If there’s a problem with your frozen application, you may see a command prompt window appear briefly when you try to run it, and then disappear again. This happens when a console-mode executable exits quickly, usually if there’s an error as soon as it starts.

There are two ways to debug what’s going on:

Freeze your application with the gui base (see Setup script or cxfreeze script). This doesn’t use a console window and reports errors in a dialog box.
Alternatively, start a command prompt yourself and launch the frozen executable from the command line. This will let you see any error messages in the console.

Freezing for other platforms¶

cx_Freeze works on Windows, Mac, and Linux, but on each platform, it only makes an executable that runs on that platform. So if you want to freeze your programs for Windows, freeze it on Windows; if you want to run it on Macs, freeze it on a Mac.

At a pinch, you can try to make a Windows executable using Wine . Our experience is that you need to copy some files manually after cx_Freeze has run to make the executable work. We don’t recommend this option.

Using data files¶

Applications often need data files besides the code, such as icons. Using a setup script, you can list data files or directories in the include_files option to build_exe. They’ll be copied to the build directory alongside the executable. Then to find them, use code like this:

def find_data_file(filename):
    if getattr(sys, "frozen", False):
        # The application is frozen
        datadir = os.path.dirname(sys.executable)
    else:
        # The application is not frozen
        # Change this bit to match where you store your data files:
        datadir = os.path.dirname(__file__)
    return os.path.join(datadir, filename)

Microsoft Visual C++ Redistributable Package¶

Python 3.8-3.12 on Windows requires the Microsoft Visual C++ Redistributable , and because of how this is installed, cx_Freeze doesn’t automatically copy it for your application.

You’re responsible for checking the license conditions associated with the DLLs you have installed.

If your license allows you to distribute these files, specify the include_msvcr option to build_exe to have them distributed automatically.
If not, your users or installers must install the Microsoft Visual C++ Redistributable Package. It’s not uncommon for this to already be present on modern computers, but, as far as we know, it’s not part of a standard Windows installation. Download the latest version or use the Winget tool on Windows 10 (build 16299 or later) or Windows 11 computers, using one of the following commands:
```
winget upgrade Microsoft.VCRedist.2015+.x64
winget upgrade Microsoft.VCRedist.2015+.x86
```
If you are using an older Windows version than Windows 10 and the latest system updates are not installed, Universal C Runtime might also be required.

Removing the MAX_PATH Limitation¶

Windows historically has limited path lengths to 260 characters. This meant that paths longer than this would not resolve and errors would result.

Support for long paths is enabled for executables built in cx_Freeze as long as the administrator activates the “Enable Win32 long paths” group policy or sets LongPathsEnabled to 1 in the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.

After changing the above option, no further configuration is required.

Single-file executables¶

Recently, the bdist_appimage command was introduced for Linux, which supports the construction of a single exe file, where all your application’s libraries are incorporated into an executable file.

On other systems, this is not supported by cx_Freeze, however, for distribution, on Windows, you can use bdist_msi, and on macOS, you can use bdist_dmg.

Also, you can use other tools to compress the build directory from cx_Freeze into a self-extracting archive:

License for frozen programs¶

When a python script is frozen with cx_Freeze, a small amount of cx_Freeze code is incorporated into the frozen program. That code is used to configure and start Python, running the script when the frozen program is launched. The incorporated cx_Freeze code is covered by the terms of the cx_Freeze Licensing, which requires a copy of the license to be included with the frozen program.

In order to make it easy to comply with this requirement, cx_Freeze will automatically include a copy of the license, as a text file, as part of the frozen program.

How to install Patchelf¶

Patchelf is used in Linux and Unix-like systems (FreeBSD, etc, except macOS). In Linux, cx_Freeze 6.10+ installs it using Patchelf wheels.

If you have any trouble with it, because your platform is not supported by binary wheels, please install it using the system package manager or from sources.

To install patchelf in debian-based:
sudo apt-get install patchelf
To install patchelf in fedora:
dnf install patchelf
Or install patchelf from sources .

Multiprocessing support¶

On Linux, macOS, and Windows, multiprocessing support is managed by cx_Freeze, including support for PyTorch torch.multiprocessing and multiprocess .

Depending on the platform, multiprocessing supports three ways to start a process. These start methods are: spawn, fork, and forkserver.

However, to produce an executable, you must use multiprocessing.freeze_support().

One needs to call this function straight after the if __name__ == "__main__" line of the main module. For example:

from multiprocessing import Process, freeze_support


def f():
    print("Hello from cx_Freeze")


if __name__ == "__main__":
    freeze_support()
    Process(target=f).start()

If the freeze_support() line is omitted, then running the frozen executable will raise RuntimeError on Windows. On Linux and macOS a similar message is shown but cx_Freeze tries to run the program by injecting a freeze_support. In addition, if the module is being run normally by the Python interpreter on any OS (the program has not been frozen), then freeze_support() has no effect.

To hide the runtime warning message, on Linux and macOS, specify in the build_exe command, the constants option with the value ‘ignore_freeze_support_message=1’. For example, using the command line:

cxfreeze --script test.py build_exe --constants='ignore_freeze_support_message=1'

Note

Contrary to what the Python docs may state, you MUST use multiprocessing.freeze_support() on Linux, macOS, and Windows. On Linux and macOS, cx_Freeze patches the call to also handle multiprocessing.spawn.freeze_support() when needed.