Distributing your application on Mac OS X

Creating self-contained applications on Mac OS X is not quite as straight-forward as it is on Windows but as long as you follow the guidance below all will be okay.

Python and PyQt

Unfortunately the current version of cx_Freeze on Mac OS X does not play particularly nicely with Python versions that have been installed from Python.org or PyQt if you have installed it previously using our instructions. Therefore, to ensure that cx_Freeze installs successfully you will need to install Python and PyQt using a package manager called MacPorts.

Thankfully, the MacPorts installation of Python and PyQt is separate from your existing installation so you do not* need to remove any files before you start.


MacPorts is a package manager for Mac OS X which is designed to make working with tools that are predominated Unix based much easier. If you have ever used a Linux distribution then you will be familiar with the concept and MacPorts works in the same way. It removes all of the hassle of compiling, maintaining and updating these tools and allows you to focus on just using them.

Installing MacPorts

To install MacPorts you will need to do the following:

  1. Ensure that you have the latest version of XCode installed (available from the Mac App Store)
  2. From within XCode install the command line tools
    • XCode menu -> Preferences -> Downloads
  3. Download the pkg installer of MacPorts for your version of Mac OS X:
  4. Run the downloaded installer for MacPorts

Using MacPorts to install Python and PyQt

MacPorts is a command line utility, which means that you will need to use the Terminal application to interact with it.

Open terminal and enter the following commands one at a time. Ensure you press enter after each command. When entering commands prefaced by sudo you may be asked for your password:

  1. sudo port selfupdate - this updates MacPorts to the latest version
  2. sudo port install py33-pyqt4 - this installs Python 3.3 and PyQt4
  3. sudo port install py33-tkinter - this installs required libraries to run IDLE

Python and PyQt should now be installed, test this out by doing the following:

  1. Open Applications/MacPorts/Python3.3/IDLE
  2. In the Python Shell type:
    • from PyQt4.QtGui import *

If there are no error messages then PyQt4 has been successfully installed.

Adding a missing library

There is another library that cx_Freeze requires to function correctly on Mac called libintl, we must install this first. Without it, any attempts to use cx_Freeze will fail.

Download the libintl library package:

  1. static linintl library package
  2. Run the package installer to install the library

Installing cx_Freeze

cx_Freeze is a utility that will take your Python program and convert it to a stand-alone application (.app) file that can be run on any Mac computer.

Getting the source

Before we can install cx_Freeze we need the source code:

If the link is broken try the cx_Freeze homepage:

Installing from source

Now that you have the source code you will need to build and install cx_Freeze. To do this you will need to make use of the Terminal application.

The video below demonstrates this.


Use the above video to install cx_Freeze from the source code you have downloaded.

Creating a script for cx_Freeze

To create a stand-alone application from your program cx_Freeze needs a script to tell it what to do. Because our programs are fairly simple (in the grand scheme of things) all we need to do is make a few changes to the sample program that is provided by cx_Freeze for use with PyQt programs.

The sample script has two lines that we are interested in:

  1. application_title = "simple_PyQt4"
  2. main_python_file = "PyQt4app.py"

You should change the values assigned to the variables application_title and main_python_file so that they are suitable for whatever program you wish to create a stand-alone application for. For example, the field simulation would be:

  1. application_title = "Field Simulation"
  2. main_python_file = "field_simulation.py"

Once you have made the necessary changes save the script and then move it so that it is in the same directory as the Python modules you want to convert to a stand-alone application.

Run the cx_Freeze script

The final step of this process is to execute the cx_Freeze script. The video demonstrates how to do this.


Use the above video to create a stand-alone application.

Final thoughts

In this section you have see how to turn your Python program into a stand-alone application that you can distribute to other people. To do this we modified an example script to get cx_Freeze to perform the necessary operations for us. However, if your application was more complex you may need to modify the script further. The documentation for cx_Freeze should be able to point you in the right direction and there is an excellent mailing list that you can join to get assistance as well.