py2app / doc / tutorial.rst

Full commit


Converting your scripts to Mac OS X applications is easy with py2app.

Create a file

The first step is to create a file for your script. is the "project file" that tells setuptools everything it needs to know to build your application. We'll use the :doc:`py2applet` script to do that:

$ py2applet --make-setup

If your application has an icon (in .icns format) or data files that it requires, you should also specify them as arguments to :doc:`py2applet`.

Clean up your build directories

Before starting development or switching development modes it's usually a good idea to ensure that your build and dist directories are cleaned out:

$ rm -rf build dist

Development with alias mode

Alias mode (the -A or --alias option) instructs py2app to build an application bundle that uses your source and data files in-place. It does not create standalone applications, and the applications built in alias mode are not portable to other machines. This mode is similar to the setuptools develop command, or Xcode's zero-link feature.

To build the application in alias mode, execute with the py2app command and specify the -A option (or --alias):

$ python py2app -A

After this, py2app will spit out a bunch of messages to your terminal and you'll end up with new build and dist folders. The build folder contains build sludge that you'll never need to touch, and the dist folder contains your application bundle. The application bundle will be named after your script; if your script was named, then your application bundle will be named Note that Finder displays application bundles without the .app extension.

You only need to run this command again when you add data files or change options. Changes to your source code won't require rebuilding!

Running your application

During development, it's often useful to have your application attached to the Terminal. This allows you to better debug it, e.g. by inserting import pdb; pdb.set_trace() into your code to inspect it interactively at runtime.

To run your application directly from the Terminal:

$ ./dist/

To start your application normally with LaunchServices, you can use the open tool:

$ open -a dist/

If you want to specify "open document" events, to simulate dropping files on your application, just specify them as additional arguments to open.

You may of course also double-click your application from Finder.

When run normally, your application's stdout and stderr output will go to the Console logs. To see them, open the Console application:

$ open -a Console

Building for deployment

After you've got your application working smoothly in alias mode, it's time to start building a redistributable version. Since we're switching from alias mode to normal mode, you should remove your build and dist folders as above.

Building a redistributable application consists of simply running the py2app command:

$ python py2app

This will assemble your application as dist/ Since this application is self-contained, you will have to run the py2app command again any time you change any source code, data files, options, etc.

The easiest way to wrap your application up for distribution at this point is simply to right-click the application from Finder and choose "Create Archive".