Python cx freeze

From wikinotes

cx_freeze lets you freeze your python application into a standalone executable.

Documentation

Official Docs https://cx-freeze.readthedocs.io/en/latest/

Install

Usage

python setup.py build_exe    # build executable
python setup.py bdist_msi    # build msi installer
python setup.py bdist_dmg    # build dmg installer
python setup.py clean --all  # note the required (--all)

Project Setup

Example

Instructions for setup.py are written in your setup.py.


setup.py

import setuptools
from cx_Freeze import setup, Executable

setup(
    executables=[Executable('project/exename.py'),
                 Executable('project/exename2.py', icon='file.ico')],

    options={'build_exe':{'packages': ['pkg_resources._vendor'],
                          'includes': []}},
)

build_exe options

cx_freeze configured using the Executable class, and the options for build_exe.
Official Documentation: http://cx-freeze.readthedocs.io/en/latest/distutils.html#build-exe

Common Options:

setup(
    options={
        'build_exe': {
            # =======
            # general
            # =======

            # change build-directory. defaults to 'build',
            'build_exe': 'alt/build',

            # compress build into zipfile (-c argument),
            'compressed': True,

            # bundle windows deps (internal only, violates windows TOS)
            'include_msvcr': True,

            # use relative-paths in stacktraces (instead of absolute paths from builder)
            'replace_paths': [('*', '')],


            # ========
            # packages
            # ========

            # paths to search for modules (defaults to sys.path value) (!WARNING!: must include python!)
            'path':     ['/src', '/other/src'],

            # list of packages to include (incl. submodules)
            'packages': ['foo'],

            # list of specific modules to include (not incl. submodules)
            'includes': ['foo', 'foo.lib', 'foo.lib.abc'],

            # list of specific modules to exclude (not incl. submodules)
            'excludes': ['bar.core', 'bar.core.constants', ..],

            # =========
            # datafiles
            # =========

            # datafiles to include. either (src,dst), or path
            'include_files': [ ('/src/file', '/dst/file'), '/path/file']
        }
    }
)

bdist_* options

cx_Freeze can also create platform-specific installers (windows(msi), osx(dmg), ...). These have their own sets of options.

setup(
    options={
        "bdist_msi": {
            "add_to_path": True,                                       # add to %PATH% variable
            "initial_target_dir": r'[ProgramFilesFolder]\MyCompany',   # control install directory
        }
    }

cx_Freeze.Executable()

executable name:

cx_Freeze.Executable(
    targetName='execute-this.exe',   # name of executable
    icon='path/to/icon.ico',         # .ico file to use as icon (must be .ico)

    # add to start-menu
    shortcutName='my-executable',
    shortcutDir='ProgramFilesFolder',  # can be any system-folder-property (see link below)
                                       # to add to desktop, use 'DesktopFolder'
)
bdist_msi desktop shortcut https://stackoverflow.com/questions/15734703/use-cx-freeze-to-create-an-msi-that-adds-a-shortcut-to-the-desktop
bdist_msi system-folder-properties https://docs.microsoft.com/en-us/windows/desktop/Msi/property-reference#system-folder-properties
creating .ico files with imagemagick imagemagick

finding datafiles

if getattr(sys, 'frozen', False):
    print('get file from frozen location')
else:
    print('get file from normal location')

Platform Notes

Windows

Console VS GUI exe

On windows you have two choices for how you want your program to run:


By default Executable('yourscript.py', base=None):

  • when run from cmd, the executable runs inside that cmd window.
  • When double clicked, a visible CMD window is created to run the .exe.

Alternatively, you may set Executable('yourscript.py', base='Win32GUI').

  • when run from cmd, the executable runs in a new, hidden cmd window. Console output is not forwarded.
  • when double clicked, the executable opens without a cmd window being created.


My solution for this is to create a myscript and myscript-cli. It's not perfect, but it is a serviceable solution.

Package notes

Some packages are more problematic than others. Here are some packages, their issue and solutions.

See cx_freeze workarounds.