.. _script:

cxfreeze script
===============

The ``cxfreeze`` script is included with other Python scripts. On Windows and
the Mac this is in the ``Scripts`` subdirectory of your Python installation
whereas on Unix platforms this in the bin directory of the prefix where Python
is installed.

Assuming you have a script called ``hello.py`` which you want to turn into an
executable, this can be accomplished by this command:

  .. code-block:: console

    cxfreeze -c hello.py --target-dir dist

Further customization can be done using the following options:

.. option:: --version

   show version number and exit

.. option:: -h, --help

   show this help message and exit

.. option:: --init-script=NAME

    script which will be executed upon startup; if the
    name of the file is not an absolute file name, the
    subdirectory initscripts (rooted in the directory in
    which the **cx_Freeze** package is found) will be searched
    for a file matching the name

.. option:: --base-name=NAME

    the filename of the base executable; if a name is given without
    an absolute path, the subdirectory bases (rooted in the directory in
    which the freezer is found) will be searched for a file matching the name

.. option:: --target-name=NAME

    the name of the target executable; the default value is the
    name of the script; the extension is optional (automatically added
    on Windows); support for names with version; if specified a
    pathname, raise an error

.. option:: --icon=ICON

    name of icon which should be included in the executable itself
    on Windows or placed in the target directory for other platforms
    (ignored by Python app from Microsoft Store)

.. option:: --manifest NAME

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

.. option:: --uac-admin

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

.. option:: --shortcut-name NAME

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

.. option:: --shortcut-dir 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)

.. option:: --copyright

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

.. option:: --trademarks

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

.. option:: --target-dir=DIR, --install-dir=DIR

    The directory in which to place the target file and any dependent files

.. option:: -O

    optimize generated bytecode as per PYTHONOPTIMIZE; use -OO in order to
    remove doc strings

.. option:: --excludes=NAMES --exclude-modules=NAMES

    comma-separated list of modules to exclude

.. option:: --includes=NAMES --include-modules=NAMES

    comma-separated list of modules to include

.. option:: --packages=NAMES

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

.. option:: --replace-paths=DIRECTIVES

    replace all the paths in modules found in the given
    paths with the given replacement string; multiple
    values are separated by the standard path separator
    and each value is of the form path=replacement_string;
    path can be * which means all paths not already
    specified

.. option:: --default-path=DIRS

   list of paths separated by the standard path separator
   for the platform which will be used to initialize
   sys.path prior to running the module finder

.. option:: --include-path=DIRS

    list of paths separated by the standard path separator
    for the platform which will be used to modify sys.path
    prior to running the module finder

.. option:: -c, --compress

    compress byte code in zip files

.. option:: --bin-includes

    comma-separated 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)

.. option:: --bin-excludes

    comma-separated 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)

.. option:: --bin-path-includes

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

.. option:: --bin-path-excludes

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

.. option:: --include-files=FILES

    comma-separated list of paths to include in distribution

.. option:: -z SPEC, --zip-include=SPEC

    additional file to include in zip file or a specification of
    the form name=arcname which will specify the archive name to use;
    multiple --zip-include arguments can be used

.. option:: --zip-include-packages=NAMES

    comma-separated 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

.. option:: --zip-exclude-packages=NAMES

    comma-separated 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 pa
    ckages 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)

.. option:: -s, --silent

    suppress all output except warnings and errors

.. option:: --include-msvcr

    include the Microsoft Visual C runtime files
