From a Python script to a portable Mac application with py2app

Do you want to share a Python script to a friend that doesn’t have Python installed? In this post you’ll learn how 🙂

With the py2app package you can compile a Python script and create a portable Mac application. If you’re using windows, you can check py2exe.

First of all, we need to install the py2app python package. If you have a virtual environment, activate it now 🙂

Next, we need to create a file for our project. In your working directory (the one that contains your Python script), type:

This will create the file, which is responsible to tell setuptools how to build your application.

If you edit this file, you should see something like:

You should put the name of your starting python script (the one your run to start) in the APP variable.

Also, if your application uses some data files, like a json or a txt file, you should include it in DATA_FILES. For example:

Now, we will compile our project in Alias mode. This instructs py2app to build an application that uses the source data files in-place. Note that this means that the application will not be portable to other machines (we’ll do that next!).

You will have two new folders inside your working directory: build and dist. The first one is used for building your app (you don’t have to touch it) and the second one contains your application bundle.

From the working directory, you can run your app using:

or you can find your application in Finder and open it from there (you’ll find it in dist/application_name).

Once your application is running, we are ready to create the stand alone version. First remove the build and dist folders with:

and next, build your application:

During the building process, I encounter some problems with the ModuleGraph package (remember that this package is installed at the same time as py2app).

If you get one of the following errors:

Edit the file where this error ocured (for me, it was inside the virtual environment folder, named myenv), at:

Look for the functions scan_code or load_module and add it an underscore before them, _scan_code and _load_module. Build again your application, it should work now 🙂

Next, try to run your app, and see if it works.

If you get errors with external packages, like certificates with httplib2 or requests, missing files in selenium webdriver, or import errors that normally work, you’ll have to fully include these packages in your application. Edit again the file and add the package that raised the error:

After saving the file, remove again the build and dist directories, build your application and try to run it. Maybe another package failed? Try to include it in the setup file and start over.

However, not all the errors you get will be solved like this, sorry…!

Once you’re application runs correctly, and you’re happy with the results, you can share it by copying the application bundle dist/application_name.

That’s all! Hope it was useful!

And please, don’t forget to share it with your friends, they might find it useful too 😉


Please, add +Marina Mele in your comments. This way I will get a notification email and I will answer you as soon as possible! :-)