{"id":8050,"library":"cx-freeze","title":"cx_Freeze","description":"cx_Freeze is a Python package that creates standalone executables from Python scripts, providing the same performance as the original script. It is cross-platform, supporting Windows, macOS, and Linux, and is actively maintained with frequent patch and minor releases. The current version is 8.6.4, supporting Python 3.10 to 3.14.","status":"active","version":"8.6.4","language":"en","source_language":"en","source_url":"https://github.com/marcelotduarte/cx_Freeze","tags":["packaging","executable","distribution","standalone","freezing"],"install":[{"cmd":"pip install cx-freeze","lang":"bash","label":"Install stable version"},{"cmd":"pip install --extra-index-url https://test.pypi.org/simple/ cx_Freeze --pre --no-cache","lang":"bash","label":"Install latest development build"}],"dependencies":[{"reason":"Requires Python >=3.10 to run cx_Freeze itself. Supports freezing applications developed with Python 3.10-3.14.","package":"Python","optional":false},{"reason":"Separated as a distinct package since cx_Freeze 8.5.0, provides core freezing functionalities.","package":"freeze-core","optional":false}],"imports":[{"note":"Used in `setup.py` scripts to define the build configuration.","symbol":"setup","correct":"from cx_Freeze import setup"},{"note":"Used in `setup.py` scripts to define the Python script to be frozen and its properties.","symbol":"Executable","correct":"from cx_Freeze import Executable"}],"quickstart":{"code":"import sys\nfrom cx_Freeze import setup, Executable\n\n# Your application's main script\nmain_script = \"hello_world.py\"\n\n# Base for a console application, change to 'Win32GUI' for GUI apps on Windows\nbase = None\nif sys.platform == \"win32\":\n    base = \"Win32GUI\" # Or None for console application\n\n# Options for the build_exe command\nbuild_exe_options = {\n    \"packages\": [], # List of packages to include\n    \"excludes\": [\"tkinter\", \"unittest\"], # List of packages to exclude\n    \"include_files\": [], # List of additional files to include (e.g., 'data.txt', 'images/')\n    \"includes\": [], # Hidden imports or dynamically loaded modules\n    \"bin_includes\": [], # Binary files dependencies\n    # \"include_msvcr\": True # For Windows, if distributing MSVC runtime DLLs\n}\n\n# Create an Executable object\nexecutables = [\n    Executable(\n        script=main_script,\n        base=base,\n        target_name=\"hello.exe\" if sys.platform == \"win32\" else \"hello\",\n        icon=None # Path to an .ico file for Windows executables\n    )\n]\n\n# Setup function call\nsetup(\n    name=\"HelloWorldApp\",\n    version=\"1.0\",\n    description=\"A simple hello world application.\",\n    options={\"build_exe\": build_exe_options},\n    executables=executables\n)\n\n# To run: Save as setup.py in the same directory as hello_world.py\n# Create hello_world.py with: print(\"Hello, cx_Freeze!\")\n# Then run in terminal: python setup.py build","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=8.6.0"},{"fix":"Manually specify such dependencies using the `includes`, `packages`, `include_files`, or `bin_includes` options in your `setup.py` `build_exe_options`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (Python 3.5+ on Windows)"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you need executables for multiple operating systems, you must build them on each respective target platform.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"cx_Freeze failed to detect and include a necessary module, or a dynamically loaded module was not explicitly included.","error":"cx_Freeze: Python error in main script / No module named 'some_module'"},{"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.","cause":"A console-mode application encountered an error immediately upon startup, causing it to exit before error messages could be read.","error":"Frozen application starts and immediately closes (Windows console window flashes briefly)."},{"fix":"Add `multiprocessing.freeze_support()` at the beginning of your main script, typically within the `if __name__ == '__main__':` block, before any `multiprocessing` calls.","cause":"This error occurs on Windows when using the `multiprocessing` module in a frozen executable without proper initialization.","error":"RuntimeError: An attempt has been made to start a new process before the current process has finished its bootstrapping phase."}]}