py2app Documentation

Alias mode (-A or --alias) is designed for rapid development. Instead of creating a standalone, portable application, it builds an application bundle that uses your source and data files in-place.

Key benefits:

• Changes to your source code do not require rebuilding the application.
• It is similar to setuptools develop mode or Xcode's zero-link feature.

Limitations:

• The resulting application is not portable and cannot be moved to other machines.

To use alias mode, run setup.py with the py2app command and the -A flag. The application bundle will be located in the dist/ folder.

$ python setup.py py2app -A

Recipes are a mechanism in py2app used to work around package incompatibilities and automatically strip unwanted dependencies. They are necessary for packages that:

1. Use __import__ or other methods to import code without using the standard import statement.
2. Require specific in-package data files to function.

Currently, py2app searches for recipes only within the py2app.recipes module.

To convert a Python script into a macOS application, you must first create a setup.py file. This file acts as the project configuration for setuptools. You can generate this file automatically using the py2applet command. If your application requires specific icon files (.icns) or additional data files, include them as arguments to the py2applet command.

$ py2applet --make-setup MyApplication.py

To install or upgrade py2app, use pip with the -m flag to ensure it is installed for your specific Python interpreter. It is recommended to use the -U flag to ensure you have the latest version.

$ python3 -mpip install -U py2app

To build a simple py2app application, create a setup.py file that uses setuptools.setup with the app parameter pointing to your main script and setup_requires set to ['py2app']. Run the build using python setup.py py2app.

"""
py2app build script for MyApplication

Usage:
    python setup.py py2app
"""
from setuptools import setup
setup(
    app=["MyApplication.py"],
    setup_requires=["py2app"],
)

Note: Using the setuptools.setup() command interface is deprecated as of version 2.0. However, it is still supported for legacy configurations.

To use this method, create a setup.py script that calls setuptools.setup() with app or plugin arguments and a py2app configuration dictionary inside the options argument.

from setuptools import setup

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

The preferred way to use py2app is as a command-line tool. It reads configuration from a pyproject.toml file in the current directory and performs the build process.

To run the build, use the following command:

$ python3 -m py2app

Once development is complete, you can build a standalone, redistributable version of your application.

Steps:

1. Clean your environment: rm -rf build dist.
2. Run the py2app command without the alias flag: python setup.py py2app.
3. The self-contained bundle will be created in dist/MyApplication.app.

Note: Unlike alias mode, any changes to source code, data files, or options require you to run the py2app command again to rebuild the bundle.

To package the final application for distribution, you can right-click the .app bundle in Finder and select "Create Archive".

$ python setup.py py2app