py2app Options

Options can be specified to py2app to influence the build procedure in three different ways:

At the command line:

$ python setup.py py2app --includes=os,platform

In your setup.py:

setup(
    app=['MyApplication.py'],
    options=dict(py2app=dict(
        includes=["os", "platform"]
    )),
)

In a setup.cfg file:

[py2app]
includes=os,platform

Note that when translating command-line options for use in setup.py, you must replace hyphens (-) with underscores (_). setup.cfg files may use either hyphens or underscores, but command-line options must always use the hyphens.

Lists of values are a comma seperated sequence of names on the command-line and in setup.cfg, and regular python lists in setup.py (as shown in the earlier example).

Option Reference

To enumerate the options that py2app supports, use the following command:

$ python setup.py py2app --help

Options for ‘py2app’ command:

Options

Command-line	Setup.py	Value	Description
--optimize	optimize	level (integer)	Specifies the optimization level for the Pytho interpreter level 0 to disable, level 1 for python -O, and level 2 for python -OO. Defaults to the optimation level of the process running py2app.
--includes	includes	list of module names	A list of Python modules to include even if they are not detected by dependency checker. Packages in this list are ignored.
--packages	packages	list of package names	A list of Python packages to include even if they are not detected by dependency checker. The whole package will be included.
--excludes	excludes	list of module or package names	A list of Python modules or packages to exclude even if they are detected by dependency checker.
--matplotlib-backends	matplotlib_backends	List of matplotlib backend names	The matplotlib backends that will be included when matplotlib is one of the included libraries. The default is to include all of matplotlib. Use ‘*’ to include all backends, and “-” to only include backends that are explicitly included.
--qt-plugins	qt_plugins	List of Qt plugins	Specifies plugins to include in an application using PyQt4.
--dylib-excludes	dylib_excludes	A list of shared libraries or frameworks	The specified libraries and frameworks will not be included in the output.
--frameworks	frameworks	A list of shared libraries or frameworks	The specified libraries and frameworks will be included in the output.
--iconfile	iconfile	Path the the icon file	Specify the icon to use for the application, the “.icns” suffix may be left off. The default is to use a generic icon.
--plist	plist	Path to a plist template, or (in setup.py) a Python dictionary.	Specify the contents of the Info.plist. Py2app will add some information to the file when it is copied into the output.
--datamodels	datamodels	List of xcdatamodels	The specified xcdatamodel files will be compiled and included into the bundle Resources
--mappingmodels	mappingmodels	List of xcmappingmodels	The specified xcmappingmodel files will be compiled and included into the bundle Resources
--resources	resources	List of files and folders	Specifies additional files and folders to include in the bundle Resource. Do not use this to copy additional code.
--extension	extensionn	file extension, includding the dot	The extension to use of the output, defaults to “.app” for applications and “.plugin” for plugins. Commonly only used for plugins.
--arch	arch	“intel”, “fat”, “universal”, “universal2”, “i386”, “x86_64”, “ppc”	The (set of) architecture(s) to use for the main executable in the output. This should be a subset of the architectures supported by the python interpreter.
--no-strip	no_strip	None (use True in setup.py)	Don’t strip debug information and local symbols from the output. Default is to strip.
--semi-standalone	semi_standalone	None (use True in setup.py)	Create output that depends on an existing installation of Python, but does contain all code and dependencies.
--alias	alias	None (use True in setup.py)	Create output that depends on an existing installation of Python and uses the sources outside of the bundle. This is only useful during development, you can update source files and relaunche the application without rebuilding the bundle. Do not use for distribution
--graph		None	Emit a “.dot” file with the module dependency graph after the build. The output will be stored next to the regular output.
--xref	xref	None	Emit a module cross reference as HTML. The output will be stored next to the regular output.
--report-missing-from-imports		None (use True in setup.py)	Include a list of missing names for from module import name in the output at the end of the py2app run.
--no-report-missing-conditional-import		None	Do not include missing modules that might be conditionally imported in the output at the end of the py2app run.
--use-faulthandler	use_faulthandler	None (use True in setup.py)	Enable the Python faulthandler, requires Python 3.3 or later.
--no-chdir	no_chdir	None	Don’t change the working directory to the bundle Resource directory. This option is always enabled in plugins.
--argv-emulation	argv_emulation	None (use True in setup.py)	Fill sys.argv during program launch. The argv emulator runs a small event loop during program launch to intercept file-open and url-open events. The to-be-opened resources will be added to sys.argv WARNING: Do no use this option when the program uses a GUI toolkit. The emulator tends to confuse GUI toolkits, and most GUI toolkits have APIs to react to these events at runtime (for example to open a file when your program is already running). This option cannot be enabled for plugins.
--emulate-shell-environment	emulate_shell_environment	None (use True in setup.py)	Set up environment variables as if the program was launched from a fresh Terminal window. Don’t use this with plugins. By default applications inherit the environment from the application launcher (when double clicking the application in the Finder), which is does not include environment variables set in the users shell profile. Only use this when the application needs to access environment varialbes set in the Terminal. This option is not meant for general use.
--use-pythonpath	use_pythonpath	None (use True in setup.py)	Allow the PYTHONPATH environment varialble to affect the interpreter’s search path. This is generally not useful, PYTHONPATH is not included in the minimal shell environment used by the application launcher.
--site-packages	site_packages	None (use True in setup.py)	Include the system and user site-packages in sys.path Note that this makes the bundle less standalone, packages installed on a users’s system may affect the bundle.
--extra-script	extra_scripts	List of file names for scripts	The mentioned scripts will be included in the Contents/MacOS. For Python scripts the file in Contents/MacOS will be a binary that launches the script using the Python interpreter and environment from the bundle.
--argv-inject	argv_inject	values to inject, a single string will be split using shlex.split	The values will be inserted in to sys.argv after argv[0].
--bdist-base	bdist_base	directory name	base directory for build library (default is build)
--dist-dir	dist_dir	directory name	directory to put the final built distributions in (default is dist)
--include-plugins	include_plugins	List of plugin bundles	The plugin bundles will be copied into the application bundle at the expected location for the type of plugin
--redirect-stdout-to-asl	redirect_stdout_to_asl	None (use True in setup.py)	Forward the stdout/stderr streams to Console.app using ASL
--force-system-tk	force_system_tk	None (use True in setup.py)	Ensures that Tkinter will be linked to the system copy of Tcl and Tk. This makes the bundle smaller, but the system version of Tcl/Tk is ancient an buggy. Don’t use this option. This is a legacy option that will be dropped in a future version
--prefer-ppc	prefer_ppc	None (use True in setup.py)	Force the application to run translated on i386 This is a legacy option that will be dropped in a future version
--debug-modulegraph	debug_modulegraph	None (use True in setup.py)	Drop into the pdb debugger after building the module graph This is an development option
--debug-skip-macholib	debug_skip_macholib	None (use True in setup.py)	Don’t run macholib. The output will not be standalone. This is an development option

Options to specify which objects to include or exclude (the first part of the table above) are used to finetune the behaviour of py2app and should generally not be necessary. Please file an issue on the py2app tracker if a package on PyPI requires one of these options, which allows me to change py2app to do the right thing automatically.