Conda

If you have Anaconda’s redistribution of Python installed, you can still use pip and PyPI, but your default package manager is conda, and your default package repository is http://anaconda.org/. We recommend following this tutorial for building packages, which ends with instructions on uploading to Anaconda.org.

If you are making a library for scientific or statistical applications—even if you don’t use Anaconda yourself—you will want to make an Anaconda distribution in order to easily reach the wide academic, commercial, and Windows-using audiences that choose Anaconda to get binaries that work without effort.

PyPI

The well-established ecosystem of tools such as PyPI and pip make it easy for other developers to download and install your package either for casual experiments, or as part of large professional systems.

If you’re writing an open source Python module, PyPI, more properly known as The Cheeseshop, is the place to host it.³ If your code isn’t packaged on PyPI, it will be harder for other developers to find it and to use it as part of their existing process. They will regard such projects with substantial suspicion of being either badly managed, not yet ready for release, or abandoned.

The definitive souce for correct, up-to-date information about Python packaging is the PyPA-maintained Python Packaging Guide.

.
|--- archive/
     |--- MyPackage/
          |--- MyPackage.tar.gz

$ cd archive
$ python3 -m SimpleHTTPServer 9000

$ pip install --extra-index-url=http://127.0.0.1:9000/ MyPackage

$ pip install http://127.0.0.1:9000/MyPackage.tar.gz

$ pip install git+https://github.com/wolever/pip2pi.git

$ pip2tgz packages/ YourPackage+

$ pip2tgz packages/ -r requirements.txt
$ dir2pi packages/

$ pip install \
  --index-url=http://your-s3-bucket/packages/simple/ \
  YourPackage+

$ pip install git+git://git.myproject.org/MyProject#egg=MyProject

PyInstaller

PyInstaller can be used to make applications on OS X, Windows, and Linux. Its primary goal is to be compatible with third-party packages out of the box—so the freeze just works.⁶ They have a list of PyInstaller supported packages. Supported graphical libraries include Pillow, pygame, PyOpenGL, PyGTK, PyQT4, PyQT5, PySide (except for Qt plug-ins), and wxPython. Supported scientific tools include NumPy, Matplotlib, Pandas, and SciPy.

PyInstaller has a modified GPL license “with a special exception which allows [anyone] to use PyInstaller to build and distribute non-free programs (including commercial ones)”—so the license(s) you must comply with will depend on the libraries you used to develop your code. Their team even provides instructions for hiding the source code for those making commercial applications or wanting to prevent others from altering the code. But do read the license (consult a lawyer if it’s important or https://tldrlegal.com/ if it’s not that important) if you need to modify their source code to build your app, because you may be required to share that change.

The PyInstaller Manual is well organized and detailed. Check the PyInstaller requirements page to confirm that your system is compatible—for Windows, you need XP or later; for Linux systems, you’ll need several terminal applications (the documentation lists where you can find them); and for OS X, you need version 10.7 (Lion) or later. You can use Wine (a Windows emulator) to cross-compile for Windows while running under Linux or OS X.

To install PyInstaller, use pip from within the same virtual environment where you are building your app:

$ pip install pyinstaller

To create a standard executable from a module named script.py, use:

$ pyinstaller script.py

To create a windowed OS X or Windows application, use the --windowed option on the command line like this:

$ pyinstaller --windowed script.spec

This creates two new directories and a file in the same folder where you executed the pyinstaller command:

• A .spec file, which can be rerun by PyInstaller to re-create the build.

• A build folder that holds some log files.

• A dist folder, that holds the main executable and some dependent Python libraries.

PyInstaller puts all the Python libraries used by your application into the dist folder, so when distributing the executable, distribute the whole dist folder.

The script.spec file can be edited to customize the build, with options to:

• Bundle data files with the executable.

• Include runtime libraries (.dll or .so files) that PyInstaller can’t infer automatically.

• Add Python runtime options to the executable.

This is useful, because now the file can be stored with version control, making future builds easier. The PyInstaller wiki page contains build recipes for some common applications, including Django, PyQt4, and code signing for Windows and OS X. This is the most current set of quick tutorials for PyInstaller. Now, the edited script.spec can be run as an argument to pyinstaller (instead of using script.py again):

$ pyinstaller script.spec

cx_Freeze

Like PyInstaller, cx_Freeze can freeze Python projects on Linux, OS X, and Windows systems. However, the cx_Freeze team does not recommend compiling for Windows using Wine because they’ve had to manually copy some files around to get the app to work. To install it, use pip:

$ pip install cx_Freeze

The easiest way to make the executable is to run cxfreeze from the command line, but you have more options (and can use version control) if you write a setup.py script. This is the same setup.py as is used by distutils in Python’s Standard Library—cx_Freeze extends distutils to provide extra commands (and modify some others). These options can be provided at the command line or in the setup script, or in a setup.cfg configuration file.

The script cxfreeze-quickstart creates a basic setup.py file that can be modified and version controlled for future builds. Here is an example session for a script named hello.py:

$ cxfreeze-quickstart
Project name: hello_world
Version [1.0]:
Description: "This application says hello."
Python file to make executable from: hello.py
Executable file name [hello]:
(C)onsole application, (G)UI application, or (S)ervice [C]:
Save setup script to [setup.py]:

Setup script written to setup.py; run it as:
    python setup.py build
Run this now [n]?

Now we have a setup script, and can modify it to match what our app needs. The options are in the cx_Freeze documentation under “distutils setup scripts.” There are also example setup.py scripts and minimal working applications that demonstrate how to freeze applications that use PyQT4, Tkinter, wxPython, Matplotlib, Zope, and other libraries in the samples/ directory of the cx_Freeze source code: navigate from the top directory to cx_Freeze/cx_Freeze/samples/. The code is also bundled with the installed library. You can get the path by typing:

$ python -c 'import cx_Freeze; print(cx_Freeze.__path__[0])'

Once you are done editing setup.py, you can use it to build your executable using one of these commands:

$ python setup.py build_exe  
$ python setup.py bdist_msi  
$ python setup.py bdist_rpm  
$ python setup.py bdist_mac  
$ python setup.py bdist_dmg  

This is the option to build the command-line executable.

This is modified by cx_Freeze from the original distutils command to also handle Windows executables and their dependencies.

This is modified from the original distutils command to ensure Linux packages are created with the proper architecture for the current platform.

This creates a standalone windowed OS X application bundle (.app) containing the dependencies and the executable.

This one creates the .app bundle and also creates an application bundle, then packages it into a DMG disk image.

py2app

py2app builds executables for OS X. Like cx_Freeze, it extends distutils, adding the new command py2app. To install it, use pip:

$ pip install py2app

Next, autogenerate a setup.py script using the command py2applet, like this:

$ py2applet --make-setup hello.py
Wrote setup.py

This makes a basic setup.py, which you can modify for your needs. There are examples with minimal working code and the appropriate setup.py scripts that use libraries including PyObjC, PyOpenGL, pygame, PySide, PyQT, Tkinter, and wxPython in py2app’s source code. To find them, navigate from the top directory to py2app/examples/.

Then, run setup.py with the py2app command to make two directores, build and dist. Be sure to clean the directories when you rebuild; the command looks like this:

$ rm -rf build dist
$ python setup.py py2app

For additional documentation, check out the py2app tutorial. The build may exit on an AttributeError. If so, read this tutorial about using py2app—the variables scan_code and load_module may need to be preceded with underscores: _scan_code and _load_module.

py2exe

py2exe builds executables for Windows. It is very popular, and the Windows version of BitTorrent was made using py2exe. Like cx_Freeze and py2exe, it extends distutils, this time adding the command py2exe. If you need to use it with Python 2, download the older version of py2exe from sourceforge. Otherwise, for Python 3.3+, use pip:

$ pip install py2exe

The py2exe tutorial is excellent (apparently what happens when documentation is hosted wiki-style rather than in source control). The most basic setup.py looks like this:

from distutils.core import setup
import py2exe

setup(
      windows=[{'script': 'hello.py'}],
)

The documentation lists all of the configuration options for py2exe and has detailed notes about how to (optionally) include icons or create a single file executable. Depending on your own license for Microsoft Visual C++, you may or may not be able to distribute the Microsoft Visual C++ runtime DLL with your code. If you can, here are the instructions to distribute the Visual C++ DLL alongside the .exe file; otherwise, you can provide your application’s users with a way to download and install the Microsoft Visual C++ 2008 redistributable packge or the Visual C++ 2010 redistributable packge if you’re using Python 3.3 or later.

Once you have modified your setup file, you can generate the .exe into dist directory by typing:

$ python setup.py py2exe

bbFreeze

The bbFreeze library currently has no maintainer and has not been ported to Python 3, but it is still frequently downloaded. Like cx_Freeze, py2app, and py2exe, it extends distutils, adding the command bbfreeze. In fact, older versions of bbFreeze were based on cx_Freeze. The appeal here may be for those who maintain legacy systems and would like to packge built distributions into eggs to be used across their infrastructure. To install it, use pip:

$ pip install bbfreeze  # bbFreeze can't work with Python3

It is light on documentation, but has build recipes for Flup, Django, Twisted, Matplotlib, GTK, and Tkinter, among others. To make executable binaries, use the command bdist_bbfreeze like this:

$ bdist_bbfreeze hello.py

It will create a directory dist in the location where bbfreeze was run that contains a Python interpreter and an executable with the same name as the script (hello.py in this case).

To generate eggs, use the new distutils command:

$ python setup.py bdist_bbfreeze

There are other options, like tagging builds as snapshots or daily builds. Get more usage information using the standard --help option:

$ python setup.py bdist_bbfreeze --help

For fine-tuning, you can use the bbfreeze.Freezer class, which is the preferred way to use bbfreeze. It has flags for whether to use compression in the created ZIP file, whether to include a Python interpreter, and which scripts to include.