Install & Compatibility
Where this runs
tested against v8.6.5.dev1781457164 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 5.08s
py 3.9
✕ build_error
✓ 5.76s
59MB installed
● package 59MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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
cxfreeze --version
Debug
Known issues
breakingThe `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.fixUpdate your `setup.py` or build scripts to use `output_name`, `product_name`, and `product_version` instead of `target_name` for `bdist_msi` configurations.
affects: >=8.6.0
gotchacx_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.fixManually specify such dependencies using the `includes`, `packages`, `include_files`, or `bin_includes` options in your `setup.py` `build_exe_options`.
affects: All versions
gotchaFor 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.fixConsider 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.
affects: All versions (Python 3.5+ on Windows)
gotchaApplications 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`.fixAdd `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.
affects: All versions
gotchacx_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.fixIf you need executables for multiple operating systems, you must build them on each respective target platform.
affects: All versions
Errors
Common errors & fixes
cx_Freeze: Python error in main script / No module named 'some_module'
cx_Freeze failed to detect and include a necessary module, or a dynamically loaded module was not explicitly included.
fixAdd 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).
A console-mode application encountered an error immediately upon startup, causing it to exit before error messages could be read.
fixRun 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.
This error occurs on Windows when using the `multiprocessing` module in a frozen executable without proper initialization.
fixAdd `multiprocessing.freeze_support()` at the beginning of your main script, typically within the `if __name__ == '__main__':` block, before any `multiprocessing` calls.
Upgrade
Version history
8.6.4latest on PyPI · released Apr 13, 2026
Audit
Dependencies
PythonrequiredRequires Python >=3.10 to run cx_Freeze itself. Supports freezing applications developed with Python 3.10-3.14.
freeze-corerequiredSeparated as a distinct package since cx_Freeze 8.5.0, provides core freezing functionalities.