Freezing Your Code

To ‘Freeze’ your code is to distribute to end-users as an executable which includes a bundled Python interpreter.

Applications such as ‘Dropbox’, BitTorrent clients, ‘Eve Online’ and ‘Civilisation IV’ do this.

The advantage of distributing this way is that your application will work even if the user doesn’t already have the required version of Python installed. On Windows, and even on many Linux distributions and OSX versions, the right version of Python will not already be installed.

One disadvantage is that it will bloat your distribution by about 2MB. Another problem is that your application will not receive any security updates to the version of Python it uses unless you freeze a new version and get users to download it.

Alternatives to Freezing

Packaging your code is for distributing libraries or tools to other developers.

On Linux, an alternative to freezing is to create a Linux distro package (e.g. .deb files for Debian or Ubuntu, or .rpm files for Red Hat and SuSE.)


Fill in “Freezing Your Code” stub


Solutions and platforms/features supported:

Solution Windows Linux OS X Python 3 License One-file mode Zipfile import Eggs pkg_resources support
bbFreeze yes yes yes no MIT no yes yes yes
py2exe yes no no yes MIT yes yes no no
pyInstaller yes yes yes yes GPL yes no yes no
cx_Freeze yes yes yes yes PSF no yes yes no
py2app no no yes yes MIT no yes yes yes


Freezing Python code on Linux into a Windows executable was only once supported in PyInstaller and later dropped..


All solutions need MS Visual C++ dll to be installed on target machine, except py2app. Only Pyinstaller makes self-executable exe that bundles the dll when passing --onefile to



Prerequisite is to install Python, Setuptools and pywin32 dependency on Windows.


Write steps for most basic .exe


Prerequisite is to install Python on Windows.

  1. Download and install
  2. Write (List of configuration options):
from distutils.core import setup
import py2exe

    windows=[{'script': ''}],
  1. (Optionally) include icon
  2. (Optionally) one-file mode
  3. Generate .exe into dist directory:
$ python py2exe
  1. Provide the Microsoft Visual C runtime DLL. Two options: globally install dll on target machine or distribute dll alongside with .exe.




PyInstaller can be used to build Unix executables and windowed apps on Mac OS X 10.6 (Snow Leopard) or newer.

To install PyInstaller, use pip:

$ pip install pyinstaller

To create a standard Unix executable, from say, use:

$ pyinstaller

This creates,

  • a script.spec file, analogous to a make file
  • a build folder, that holds some log files
  • a dist folder, that holds the main executable script, and some dependent Python libraries,

all in the same folder as PyInstaller puts all the Python libraries used in into the dist folder, so when distributing the executable, distribute the whole dist folder.

The script.spec file can be edited to customise the build, with options such as

  • bundling data files with the executable
  • including run-time libraries (.dll or .so files) that PyInstaller can’t infer automatically
  • adding Python run-time options to the executable,

Now script.spec can be run with pyinstaller (instead of using again):

$ pyinstaller script.spec

To create a standalone windowed OS X application, use the --windowed option

$ pyinstaller --windowed script.spec

This creates a in the dist folder. Make sure to use GUI packages in your Python code, like PyQt or PySide, to control the graphical parts of the app.

There are several options in script.spec related to Mac OS X app bundles here. For example, to specify an icon for the app, use the icon=\path\to\icon.icns option.