py2app Setuptools Configuration¶

Setup function arguments¶

The primary way to configure py2app is to use a “setup.py” script that calls setuptools.setup() with a number of specific arguments.

The basic structure:

from setuptools import setup

setup(
    app=...
    options={
        "py2app"={
            ...
        }
    }
)

The following keyword arguments are used by py2app:

name

Name of the application or plugin bundle. The name is also included as the CFBundleName in the Info.plist file.

By default this is derived from the name of the main script.
version

The version of the application or plugin bundle, will be included in the Info.plist (unless the specified plist already contains a CFBundleVersion key).

When this keyword argument is not used py2app tries to find a toplevel assignment of a constant string to __version__ in the main script, and uses the last one found. The version is set to 0.0.0 When there is no such assignment, or the last assignment uses an expression or non-string value.
app

A list of application scripts, each of which will by used to generate an application bundle. This must be a list of 1 item.

Entries in the list are one of:
- A string with the filename of the main script of the application;
- A dictionary with the following keys (only script is required):
  - script: A string with the filename of the main script for the application
  - plist: A dictionary with the contents of the plist file
  - extra_scripts: A list of filenames of scripts that will have a launcher included in the Contents/MacOS folder.
This keyword argument is mutually exclusive with plugin.
plugin

A list of plugin scripts, each of which will by used to generate a plugin bundle. This must be a list of 1 item.

Entries in the list are one of:
- A string with the filename of the main script of the plugin;
- A dictionary with the following keys (only script is required):
  - script: A string with the filename of the main script for the plugin
  - plist: A dictionary with the contents of the plist file
  - extra_scripts: A list of filenames of scripts that will have a launcher included in the Contents/MacOS folder.
This keyword argument is mutually exclusive with app.
data_files

A list of data files to include in the Resources folder in the generated bundle. Entries of this list should be one of the following:
- A string specifying the path to a resource (file or folder). These are copied into the Resources folder
- A two-tuple (dirname, [file, ...]). The dirname is a folder name relative to the Resources folder, and the file-s are the names of sources (files or folders) copied into the specified folder.
options

The options argument should be a directory, where the py2app key contains py2app configuration options, as specified below.

Configuration 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={
        "py2app": {
             "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 separated 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 optimization 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.
`--maybe-packages`	maybe_packages	list of package names	A list of Python packages to include outside of the zipfile when detected as a dependency by the dependency checker.
`--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.
`--expected-missing-imports`	expected_missing_imports	list of module or package names	A list of Python module/package names that are expected to be missing, or a string starting with a @-sign followed by the name of file containing this list (one name per line). This is used to fine-tune error reporting.
`--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 variables 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
`--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.

py2app Setuptools Configuration¶

Setup function arguments¶

Configuration options¶

Option Reference¶

Table of Contents

Previous topic

Next topic

This Page