Setup script#

cx_Freeze creates four new commands and subclasses four others in order to provide the ability to both build and install executables. In typical setuptools fashion they can be provided in the setup script (it is called setup.py by convention, although it can have any name), in a pyproject.toml configuration file, in a setup.cfg configuration file, or on the command line. They are described in further detail below.

Example#

It looks something like this:

from cx_Freeze import setup, Executable

# Dependencies are automatically detected, but it might need fine tuning.
build_exe_options = {
    "excludes": ["tkinter", "unittest"],
    "zip_include_packages": ["encodings", "PySide6", "shiboken6"],
}

setup(
    name="guifoo",
    version="0.1",
    description="My GUI application!",
    options={"build_exe": build_exe_options},
    executables=[Executable("guifoo.py", base="gui")],
)

The script is invoked as follows:

python setup.py build

Note

There are more examples in the samples directory.

This command will create a subdirectory called build with a further subdirectory starting with the letters exe. and ending with the typical identifier for the platform and python version. This allows for multiple platforms to be built without conflicts.

To specify options in the script, use underscores in the name. For example:

# ...
zip_include_packages = ["encodings", "PySide6", "shiboken6"]

To specify the same options on the command line, use dashes, like this:

python setup.py build_exe --zip-include-packages=encodings,PySide6,shiboken6

On Windows, you can build a simple installer containing all the files cx_Freeze includes for your application, by running the setup script as:

python setup.py bdist_msi

On Mac OS X, you can use bdist_mac to create a Mac application bundle or bdist_dmg to build a Mac disk image.

Commands#

build#

This command is a standard command which has been modified by cx_Freeze to build any executables that are defined. The following options were added to the standard set of options for the command:

option name

description

build_exe#

directory for built executables and dependent files, defaults to the value of the “build_exe” option on the build_exe command (see below); note that this option is overwritten by the corresponding option on the build_exe command

Deprecated since version 6.14: build_exe option. To be removed in version 6.18 or 7.0.

This is the equivalent help to specify the same options on the command line:

python setup.py build --help
Options for 'build' command:
  --build-base (-b)  base directory for build library
  --build-exe        directory for built executables and dependent files
  (...)
  --compiler (-c)    specify the compiler type
  --help-compiler    list available compilers

build_exe#

This command performs the work of building an executable or set of executables. It can be further customized:

option name

description

build_exe#

directory for built executables and dependent files, defaults to a directory of the form build/exe.[platform identifier].[python version]

optimize#

optimization level, one of 0 (disabled), 1 or 2

excludes#

comma-separated list of names of modules to exclude

includes#

comma-separated list of names of modules to include

packages#

comma-separated list of packages to include, which includes all submodules in the package

replace_paths#

comma-separated list of paths to replace in the code object of included modules, using the form <search>=<replace>; search can be * which means all paths not already specified, leaving just the relative path to the module; multiple values are separated by the standard path separator

path#

comma-separated list of paths to search for modules; the default value is sys.path (use only if you know what you are doing)

include_path#

comma-separated list of paths to modify the search for modules

no_compress#

create a zipfile with no compression

constants#

comma-separated list of constant values to include in the constants module called BUILD_CONSTANTS in the form <name>=<value>

bin_includes#

list of files to include when determining dependencies of binary files that would normally be excluded, using first the full file name, then just the base file name, then the file name without any version numbers (the version numbers that normally follow the shared object extension are stripped prior to performing the comparison)

bin_excludes#

list of files to exclude when determining dependencies of binary files that would normally be included, using first the full file name, then just the base file name, then the file name without any version numbers (the version numbers that normally follow the shared object extension are stripped prior to performing the comparison)

bin_path_includes#

list of paths from which to include files when determining dependencies of binary files

bin_path_excludes#

list of paths from which to exclude files when determining dependencies of binary files

include_files#

list containing files to be copied to the target directory; it is expected that this list will contain strings or 2-tuples for the source and destination; the source can be a file or a directory (in which case the tree is copied except for .git, .svn and CVS directories); the target must not be an absolute path

zip_includes#

list containing files to be included in the zip file directory; it is expected that this list will contain strings or 2-tuples for the source and destination

zip_include_packages#

list of packages which should be included in the zip file; the default is for all packages to be placed in the file system, not the zip file; those packages which are known to work well inside a zip file can be included if desired; use * to specify that all packages should be included in the zip file

zip_exclude_packages#

list of packages which should be excluded from the zip file and placed in the file system instead; the default is for all packages to be placed in the file system since a number of packages assume that is where they are found and will fail when placed in a zip file; use * to specify that all packages should be placed in the file system and excluded from the zip file (the default)

silent#

suppress all output except warnings (equivalent to silent_level=1)

silent_level#

suppress output from freeze process; can provide a value to specify what messages should be suppressed, with the possible values being:

  1. do not suppress any output [default];

  2. suppress information messages;

  3. also suppress missing-module warning messages;

  4. also suppress all other warning messages.

include_msvcr#

include the Microsoft Visual C runtime files without needing the redistributable package installed

New in version 6.7: silent_level option.

This is the equivalent help to specify the same options on the command line:

python setup.py build_exe --help
Options for 'build_exe' command:
--build-exe (-b)        directory for built executables and dependent files
--optimize (-O)         optimization level: -O1 for "python -O", -O2 for
                        "python -OO" and -O0 to disable [default: -O0]
--excludes (-e)         comma-separated list of modules to exclude
--includes (-i)         comma-separated list of modules to include
--packages (-p)         comma-separated list of packages to include, which
                        includes all submodules in the package
--replace-paths         comma-separated list of paths to replace in included
                        modules, using the form <search>=<replace>
--path                  comma-separated list of paths to search for modules;
                        the default value is sys.path (use only if you know
                        what you are doing)
--include-path          comma-separated list of paths to modify the search
                        for modules
--no-compress           create a zipfile with no compression
--constants             comma-separated list of constants to include
--bin-includes          list of files to include when determining
                        dependencies of binary files that would normally be
                        excluded
--bin-excludes          list of files to exclude when determining
                        dependencies of binary files that would normally be
                        included
--bin-path-includes     list of paths from which to include files when
                        determining dependencies of binary files
--bin-path-excludes     list of paths from which to exclude files when
                        determining dependencies of binary files
--include-files (-f)    list of tuples of additional files to include in
                        distribution
--zip-includes          list of tuples of additional files to include in zip
                        file
--zip-include-packages  comma-separated list of packages to include in the
                        zip file (or * for all) [default: none]
--zip-exclude-packages  comma-separated list of packages to exclude from the
                        zip file and place in the file system instead (or *
                        for all) [default: *]
--silent (-s)           suppress all output except warnings (equivalent to
                        --silent-level=1)
--silent-level          suppress output from build_exe command. level 0: get
                        all messages; [default] level 1: suppress
                        information messages, but still get warnings;
                        (equivalent to --silent) level 2: suppress missing
                        missing-module warnings level 3: suppress all
                        warning messages
--include-msvcr         include the Microsoft Visual C runtime files

install#

This command is a standard command which has been modified by cx_Freeze to install any executables that are defined. The following options were added to the standard set of options for the command:

option name

description

install_exe#

directory for installed executables and dependent files

install_exe#

This command performs the work installing an executable or set of executables. It can be used directly but most often is used when building Windows installers or RPM packages. It can be further customized:

option name

description

install_dir#

directory to install executables to; this defaults to a subdirectory called <name>-<version> in the “Program Files” directory on Windows and <prefix>/lib on other platforms; on platforms other than Windows symbolic links are also created in <prefix>/bin for each executable.

build_dir#

build directory (where to install from); this defaults to the build_dir from the build command

force#

force installation, overwriting existing files

skip_build#

skip the build steps

This is the equivalent help to specify the same options on the command line:

python setup.py install_exe --help
Options for 'install_exe' command:
  --install-dir (-d)  directory to install executables to
  --build-dir (-b)    build directory (where to install from)
  --force (-f)        force installation (overwrite existing files)
  --skip-build        skip the build steps

bdist_appimage#

This command is available on Linux systems, to create a AppImage application bundle (a .AppImage file); bdist_appimage automates the process.

An AppImage is a downloadable file for Linux that contains an application and everything the application needs to run (e.g., libraries, icons, fonts, translations, etc.) that cannot be reasonably expected to be part of each target system.

New in version 6.17.

option name

description

appimagekit#

path to AppImageKit (download the latest version if not specified).

bdist_dir#

temporary directory for creating the distribution

dist_dir (-d)#

directory to put final built distributions in (default: dist)

skip_build#

skip rebuilding everything (for testing/debugging)

target_name#

name of the file to create

target_version#

version of the file to create

silent (-s)#

suppress all output except warnings

This is the equivalent help to specify the same options on the command line:

python setup.py bdist_appimage --help

bdist_msi#

This command is a standard command in Python 2.5 and higher which has been modified by cx_Freeze to handle installing executables and their dependencies. The following options were added to the standard set of options for the command:

option name

description

add_to_path#

add the target directory to the PATH environment variable; the default value is True if there are any console based executables and False otherwise

all_users#

perform installation for all users; the default value is False and results in an installation for just the installing user

data#

dictionary of arbitrary MSI data indexed by table name; for each table, a list of tuples should be provided, representing the rows that should be added to the table. For binary values (e.g. Icon.Data), pass the path to the file containing the data.

summary_data#

dictionary of data to include in MSI summary information stream (allowable keys are “author”, “comments”, “keywords”)

directories#

list of directories that should be created during installation

environment_variables#

list of environment variables that should be added to the system during installation

initial_target_dir#

defines the initial target directory supplied to the user during installation; in order to specify a target directory of “XYZ” in the default program directory use “[ProgramFiles64Folder]XYZ” or “[ProgramFilesFolder]XYZ” (for the default 64-bit or non-64 bit locations, respectively)

install_icon#

path of icon to use for the add/remove programs window that pops up during installation

product_code#

define the product code for the package that is created

target_name#

specifies the name of the file that is to be created; if the name ends with “.msi” then it is used verbatim, otherwise information about program version and platform will be added to the installer name

upgrade_code#

define the GUID of the upgrade code for the package that is created; this is used to force removal of any packages created with the same upgrade code prior to the installation of this one; the valid format for a GUID is {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} where X is a hex digit. Refer to Windows GUID.

extensions#

list of dictionaries specifying the extensions that the installed program handles. Each extension needs to specify at least the extension, a verb, and an executable. Additional allowed keys are argument to specify the invocation of the executable, mime for the extension’s mime type, and context for the context menu text.

New in version 6.7: extensions option.

This is the equivalent help to specify the same options on the command line:

python setup.py bdist_msi --help

For example:

directory_table = [
    ("ProgramMenuFolder", "TARGETDIR", "."),
    ("MyProgramMenu", "ProgramMenuFolder", "MYPROG~1|My Program"),
]

msi_data = {
    "Directory": directory_table,
    "ProgId": [
        ("Prog.Id", None, None, "This is a description", "IconId", None),
    ],
    "Icon": [
        ("IconId", "icon.ico"),
    ],
}

bdist_msi_options = {
    "add_to_path": True,
    "data": msi_data,
    "environment_variables": [
        ("E_MYAPP_VAR", "=-*MYAPP_VAR", "1", "TARGETDIR")
    ],
    "upgrade_code": "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}",
}

build_exe_options = {"excludes": ["tkinter"], "include_msvcr": True}

executables = [
    Executable(
        "hello.py",
        copyright="Copyright (C) 2024 cx_Freeze",
        base="gui",
        icon="icon.ico",
        shortcut_name="My Program Name",
        shortcut_dir="MyProgramMenu",
    )
]

setup(
    name="hello",
    version="0.1",
    description="Sample cx_Freeze script to test MSI arbitrary data stream",
    executables=executables,
    options={
        "build_exe": build_exe_options,
        "bdist_msi": bdist_msi_options,
    },
)

Samples: There are more examples in the samples directory.

bdist_rpm#

This command is available on Linux systems; It creates an RPM distribution.

Please check the options on the command line:

python setup.py bdist_rpm --help

bdist_deb#

This command is available on Linux systems; It is a simple wrapper around ‘alien’ that creates an RPM distribution, then converts to a DEB distribution.

New in version 6.16.

Please check the options on the command line:

python setup.py bdist_deb --help

bdist_mac#

This command is available on Mac OS X systems, to create a Mac application bundle (a .app directory).

option name

description

iconfile#

Path to an icns icon file for the application. This will be copied into the bundle.

qt_menu_nib#

Path to the qt-menu.nib file for Qt applications. By default, it will be auto-detected.

bundle_name#

File name for the bundle application without the .app extension.

plist_items#

A list of key-value pairs (type: List[Tuple[str, str]]) to be added to the app bundle Info.plist file. Overrides any specific entries set by custom_info_plist or be default.

custom_info_plist#

File to be used as the Info.plist in the app bundle. If not specified, A basic Info.plist will be generated by default, which specifies CFBundleIconFile, CFBundleDevelopmentRegion, CFBundleIdentifier, CFBundlePackageType, and NSHighResolutionCapable.

include_frameworks#

A list of Framework directories to include in the app bundle.

include_resources#

A list of tuples of additional files to include in the app bundle’s resources directory, with the first element being the source, and second the destination file or directory name.

codesign_identity#

The identity of the key to be used to sign the app bundle.

codesign_entitlements#

The path to an entitlements file to use for your application’s code signature.

codesign_timestamp#

Use –timestamp when running codesign.

codesign_strict#

Use –strict when running codesign.

codesign_verify#

Use –verify when running codesign.

spctl_assess#

Run spctl-assess to asses output from codesign.

codesign_deep#

Boolean for whether to codesign using the –deep option.

codesign_options#

Comma seperated string of options to use with codesign –options.

codesign_resource_rules#

Plist file to be passed to codesign’s –resource-rules option.

absolute_reference_path#

Path to use for all referenced libraries instead of @executable_path

New in version 6.0: environment_variables, include_resources, absolute_reference_path and rpath_lib_folder options.

Changed in version 6.0: Replaced the compressed option with the no_compress option.

Deprecated since version 6.5: rpath_lib_folder option. Removed in version 6.12.

This is the equivalent help to specify the same options on the command line:

python setup.py bdist_mac --help

bdist_dmg#

This command is available on Mac OS X systems; it creates an application bundle, then packages it into a DMG disk image suitable for distribution and installation.

option name

description

volume_label#

Volume label of the DMG disk image

applications_shortcut#

Boolean for whether to include shortcut to Applications in the DMG disk image

silent (-s)#

suppress all output except warnings

This is the equivalent help to specify the same options on the command line:

python setup.py bdist_dmg --help

cx_Freeze.Executable#

The options for the build_exe command are the defaults for any executables that are created. The options for the Executable class allow specification of the values specific to a particular executable. The arguments to the constructor are as follows:

argument name

description

script#

the name of the file containing the script which is to be frozen

init_script#

the name of the initialization script that will be executed before the actual script is executed; this script is used to set up the environment for the executable; if a name is given without an absolute path the names of files in the initscripts subdirectory of the cx_Freeze package is searched

base#

the name of the base executable; the pre-defined values are: “console” (default), “gui” and “service”; a user-defined base is accepted if it is given with an absolute path name

target_name#

the name of the target executable; the default value is the name of the script; it is recommended NOT to use an extension (automatically added on Windows); target-name with version is supported; if specified a path, raise an error

icon#

name of icon which should be included in the executable itself on Windows (ignored by Python app from Microsoft Store) or placed in the target directory for other platforms; it is recommended NOT to use an extension (automatically added “.ico” on Windows, “.icns” on macOS and “.png” or “.svg” on Linux and others)

manifest#

name of manifest which should be included in the executable itself (Windows only - ignored by Python app from Microsoft Store)

uac_admin#

creates a manifest for an application that will request elevation (Windows only - ignored by Python app from Microsoft Store)

uac_uiaccess#

changes the application manifest to bypass user interface control (Windows only - ignored by Python app from Microsoft Store)

shortcut_name#

the name to give a shortcut for the executable when included in an MSI package (Windows only)

shortcut_dir#

the directory in which to place the shortcut when being installed by an MSI package; see the MSI Shortcut table documentation for more information on what values can be placed here (Windows only).

the copyright value to include in the version resource associated with executable (Windows only)

trademarks#

the trademarks value to include in the version resource associated with the executable (Windows only)

New in version 6.10: manifest and uac_admin options.

New in version 6.16: uac_uiaccess option.

Changed in version 6.5: Arguments are all snake_case (camelCase removed in 6.15).

Note

  1. setup accepts a list of Executable

  2. target_name has been extended to support version, like target_name=”Hello-0.1” or target_name=”Hello.0.1.exe”

  3. the name of the target executable can be modified after the build only if one Executable is built.