cx_Freeze

Common errors

• cx_Freeze: Python error in main script / No module named 'some_module'

  cause cx_Freeze failed to detect and include a necessary module, or a dynamically loaded module was not explicitly included.
  fix Add the missing module to the `includes` or `packages` list in your `build_exe_options` in `setup.py`. For data files, use `include_files`.

• Frozen application starts and immediately closes (Windows console window flashes briefly).

  cause A console-mode application encountered an error immediately upon startup, causing it to exit before error messages could be read.
  fix Run the executable from a command prompt to see the error output, or for GUI applications, set `base="Win32GUI"` in the `Executable` definition in `setup.py` to display errors in a dialog box.

• RuntimeError: An attempt has been made to start a new process before the current process has finished its bootstrapping phase.

  cause This error occurs on Windows when using the `multiprocessing` module in a frozen executable without proper initialization.
  fix Add `multiprocessing.freeze_support()` at the beginning of your main script, typically within the `if __name__ == '__main__':` block, before any `multiprocessing` calls.

Warnings

• breaking The `bdist_msi` command for creating Windows installers had its options refactored in version 8.6.0. The `target_name` option was removed and replaced by `output_name`, `product_name`, and `product_version` to work better with pyproject.
  Fix: Update your `setup.py` or build scripts to use `output_name`, `product_name`, and `product_version` instead of `target_name` for `bdist_msi` configurations.
• gotcha cx_Freeze might not automatically detect and include modules or data files that are dynamically loaded (e.g., via `importlib.import_module` or plugin systems). This can lead to `ModuleNotFoundError` or missing files at runtime.
  Fix: Manually specify such dependencies using the `includes`, `packages`, `include_files`, or `bin_includes` options in your `setup.py` `build_exe_options`.
• gotcha For Windows executables, particularly with Python 3.5+, the Microsoft Visual C++ Redistributable might not be automatically copied. Users running your frozen application on systems without it may encounter errors.
  Fix: Consider setting `include_msvcr=True` in your `build_exe_options` in `setup.py` if your license allows redistribution, or ensure users install the appropriate Microsoft Visual C++ Redistributable Package.
• gotcha Applications using the `multiprocessing` module, especially on Windows, must include `multiprocessing.freeze_support()` at the very beginning of the main script or the entry point that uses multiprocessing to prevent a `RuntimeError`.
  Fix: Add `multiprocessing.freeze_support()` at the top of your main script, within the `if __name__ == '__main__':` block, before any other code that imports `multiprocessing` or creates child processes.
• gotcha cx_Freeze typically creates executables that are specific to the platform they were built on. A Windows executable cannot run on Linux or macOS, and vice-versa.
  Fix: If you need executables for multiple operating systems, you must build them on each respective target platform.

Install

• pip install cx-freeze Install stable version
• pip install --extra-index-url https://test.pypi.org/simple/ cx_Freeze --pre --no-cache Install latest development build

Imports

• setup

  from cx_Freeze import setup

  Used in `setup.py` scripts to define the build configuration.
• Executable

  from cx_Freeze import Executable

  Used in `setup.py` scripts to define the Python script to be frozen and its properties.

Quickstart

Create a `setup.py` file to configure cx_Freeze. This script specifies the main Python file to freeze, build options, included packages, and additional files. After creating `setup.py` and your main script (e.g., `hello_world.py`), run `python setup.py build` in your terminal to generate the executable. For Windows GUI applications, set `base="Win32GUI"` to prevent a console window from appearing.

import sys
from cx_Freeze import setup, Executable

# Your application's main script
main_script = "hello_world.py"

# Base for a console application, change to 'Win32GUI' for GUI apps on Windows
base = None
if sys.platform == "win32":
    base = "Win32GUI" # Or None for console application

# Options for the build_exe command
build_exe_options = {
    "packages": [], # List of packages to include
    "excludes": ["tkinter", "unittest"], # List of packages to exclude
    "include_files": [], # List of additional files to include (e.g., 'data.txt', 'images/')
    "includes": [], # Hidden imports or dynamically loaded modules
    "bin_includes": [], # Binary files dependencies
    # "include_msvcr": True # For Windows, if distributing MSVC runtime DLLs
}

# Create an Executable object
executables = [
    Executable(
        script=main_script,
        base=base,
        target_name="hello.exe" if sys.platform == "win32" else "hello",
        icon=None # Path to an .ico file for Windows executables
    )
]

# Setup function call
setup(
    name="HelloWorldApp",
    version="1.0",
    description="A simple hello world application.",
    options={"build_exe": build_exe_options},
    executables=executables
)

# To run: Save as setup.py in the same directory as hello_world.py
# Create hello_world.py with: print("Hello, cx_Freeze!")
# Then run in terminal: python setup.py build