py2app 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 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.