py2app

0.28.10 verified Fri May 01 auth: no python

py2app is a Python setuptools command that allows you to create standalone macOS application bundles (.app) from Python scripts, including all dependencies. The current version is 0.28.10, requiring Python >=3.10. It wraps py2applet and the py2app build command, with recipes for many popular third-party packages.

pip install py2app

Common errors

error ImportError: cannot import name 'log' from 'py2app' ↓

cause Incorrect import path; py2app is a command, not a library.

fix

Use 'from py2app.command import py2app' or simply run via setup.py.

error SystemExit: error: option --no-user-cfg not recognized ↓

cause Conflict with setuptools version; often due to using older py2app with newer setuptools.

fix

Upgrade py2app: pip install --upgrade py2app. Minimum 0.28.9 for setuptools >=70.

error DistributionNotFound: The 'py2app' distribution was not found ↓

cause py2app not installed in the current environment or not listed in setup_requires.

fix

Run 'pip install py2app' and ensure 'setup_requires' includes 'py2app' in setup.py.

error ValueError: The 'app' script is not a Python script ↓

cause The file specified in APP list is not a Python file or does not exist.

fix

Check that the path in APP list is a valid .py file.

Warnings

gotcha install_requires in setup() no longer works with py2app. Use setup_requires=['py2app'] instead. ↓

fix Move py2app requirement from install_requires to setup_requires.

breaking py2app requires Python >=3.10 as of 0.28.10. Older versions of Python (including 2.7 and 3.9) are no longer supported. ↓

fix Upgrade to Python 3.10+ or pin py2app to an older version (e.g., <=0.28.8).

gotcha py2app does not support free-threaded Python (3.13+ with --disable-gil). ↓

fix Use standard CPython without free-threading for building apps with py2app.

deprecated pkg_resources usage is deprecated; fallback only for ancient Python versions. ↓

fix Ensure your application does not rely on pkg_resources; modern setuptools uses importlib.resources.

Imports

py2app.command.py2app
wrong
```
import py2app
```
correct
```
from py2app.command import py2app
```
py2app is a command extension, not a direct module; the correct import is for internal use.

Quickstart

Minimal setup.py to build a macOS .app from hello.py. Run 'python setup.py py2app' to build.

# setup.py
from setuptools import setup

APP = ['hello.py']
DATA_FILES = []
OPTIONS = {}

setup(
    app=APP,
    data_files=DATA_FILES,
    options={'py2app': OPTIONS},
    setup_requires=['py2app'],
)