Py2app Configuration

Introduction

As of py2app 2.0 the primary way to configure a build is using configurration in pyproject.toml (as introduced in PEP 518). Note that py2app is not a build system as described in PEP 518, using py2app as the build-backend in the build-system table is not supported and will result in an error.

Configuration for py2app is stored in the tools.py2app table.

A basic example of a configuration file:

[tools.py2app.bundle.main]

script = "main.py"
semi-standalone = true

The configuration for bundles supports defining multiple bundles, but for now only a single bundle is supported. The convention is to use main as the subkey for the primary bundle.

Global options

The options can also be included in the bundle configuration described below, and generally have a command-line equivalent as well.

Key Value Type (TOML) Description
build-type string

The type of build, one of:

  • standalone (default): Create a bundle that can be used on a different machine.
  • semi-standalone: Create a bundle that embeds all resources except the python interpreter
  • alias: Debug builds that links to source files instead of copying them into the bundle.
strip bool Strip debug information and local system from MachO files included in the bundle. Defaults to true.
deployment-target string Deployment target for the output of py2app. Defaults to the deployment target of the Python interpreter.
arch string

The set of CPU architectures to include (x86_64, arm64 or universal2). Defaults to the architecture(s) of the Python interpreter.

Defaults to the set of architectures of the active interpreter.
python.optimize int Optimization level for the Python interpreter. Defaults to the level for the current interpreter.
python.verbose bool Start the Python interpreter in verbose mode (default false)
python.use_pythonpath bool Use the PYTHONPATH environment variable when it is set (default false)
python.use_sitepackages bool Use the site-packages directory for a semi-standalone
python.faulthandler bool Enable faulthandler (default false).

Bundle configuration

Configuration for a bundle can contain the following keys:

Key Value Type (TOML) Description
name string (Optional) Name of the bundle (without extension). Default is same as the basename of script.
script string Path to the main script.
plugin boolean (Optional) Set to true for plugin bundles. Default is false.
extension string File extension for the bundle (excluding the dot). Defaults to app for application bundles and bundle for plugin bundles.
include array of string

Array of modules or packages to include even when they are not detected by the dependency checker.

Note that packages will only include the package itself and anything found relative to the package __init__.
exclude array of string Array of modules or packages that won’t be included even when detected by the dependency checker.
full-package array of string Array of packages that will be included entirely when they are part of the dependency graph.
dylib-include array of string Array of shared libraries and frameworks that will be included, even if not detected by the dependency checker.
dylib-exclude array of string Array of shared libraries and frameworks that will not be included.
iconfile string Path for the icon file to use. Default is a generic icon.
resources see below Description of data files to include in the bundle.
plist table

Contents for the Info.plist file, will be merged with a py2app template.

For simple programs this can can be left out.
chdir bool Change directory to the “Contents/Resources” folder. Defaults to true for application bundles and false for plugin bundles.
argv-emulator bool

Fill sys.argv by waiting for open events during startup. Defaults to false.

This option can only be used for application bundles, and should not be used with GUI frameworks (which generally have their own mechanism for handling open events).
argv-inject array of string Values that will be appended to sys.argv during startup
emulate-shell-environment bool Emulate the environment variables from a Terminal window by running a login shell in the background and extracting environment variables. Defaults to false.
extra-scripts array of string Additional script that should be included in the bundle, will be setup for command-line invocation.
redirect-to-asl bool Redirect the stdout and stderr streams to Console.app using ASL. Defaults to false. Deprecated, do no use.

For now only a single bundle is supported. In the future there will be support for multiple bundles, including embedding bundles (e.g. an application with embedded plugins).

Code signing configuration

Configuration for code signing is stored in the tools.py2app.codesign table. And can be stored in a codesign subtable for specific bundles.

This section is intentionally left blank.

Recipe configuration

Configuration for the recipe system is stored in the tools.py2app.recipes table. And can be stored in a recipes subtable for specific bundles.

Key Value Type (TOML) Description
zip-unsafe array of string Array of packages and modules that are not safe to include in site-packages.zip. Please file an issue with py2app for distributions on PyPI that are not zip-safe.
qt-plugins array of string The Qt plugins to include in the bundle for scripts using PyQt or PySide. Defaults to an empty array.
matplotlib-backends array of string The matplotlib backends to include for scripts using this library. Defaults to all backends.