Create a single executable from a Python project

Question

I want to create a single executable from my Python project. A user should be able to download and run it without needing Python installed. If I were just distributing a package, I could use pip, wheel, and PyPI to build and distribute it, but this requires that the user has Python and knows how to install packages. What can I use to build a self-contained executable from a Python project?

Solution 1

Here are some common ones. I've included only projects that are being actively maintained as of my last edit (July 2021).

Unless otherwise noted, all programs listed below will produce an exe specifically for the operating system it's running in. So for example, running Pyinstaller in Windows will produce a Windows exe, but running Pyinstaller in Linux will produce a Linux exe. If you want to produce an exe for multiple operating systems, you will have to look into using virtual machines or something like Wine.

---

The following programs all work similarly -- they bundle together Python and your program, effectively combining them to produce an executable.

• PyInstaller:

  Website || Repo || PyPi

  Supports Python 3.5 - 3.9 on Windows, Mac, and Linux.

• cx_Freeze:

  Website || Repo || PyPi

  Supports Python 3.6 - 3.9 on Windows, Mac, and Linux.

• py2exe:

  Website || Repo || PyPi

  Supports Python 3.6 - 3.9 on Windows only.

• py2app:

  Website || Repo || PyPi

  Supports Python 2.7 (?) and Python 3 (?) on Macs only. The exact range of supported Python versions is currently undocumented.

---

Of course, that's not the only way of doing things:

• pynsist:

  Website || Repo || PyPi

  Pynsist will create a Windows installer for your program which will directly install Python on the user's computer instead of bundling it with your code and create shortcuts that link to your Python script.

  The pynsist tool itself requires Python 3.5+ to run, but supports bundling any version of Python with your program.

  Pynsist will create Windows installers only, but can be run from Windows, Mac, and Linux. See their FAQ for more details.

• Nuitka:

  Website || Repo (Github mirror) || PyPi

  Nuitka will literally compile your Python code and produce an exe (as opposed to the other projects, which simply include Python) to try and speed up your code. As a side effect, you'll also get a handy exe you can distribute. Note that you need to have a C++ compiler available on your system.

  Supports Python 2.6 - 2.7 and Python 3.3 - 3.9 on Windows, Mac, and Linux.

• cython:

  Website || Repo || PyPi

  Cython is similar to Nuitka in that it is a Python compiler. However, instead of directly compiling your code, it'll compile it to C. You can then take that C code and turn your code into an exe. You'll need to have a C compiler available on your system.

  Supports Python 2.6 - 2.7 and Python 3.3 - 3.9 on Windows, Mac, and Linux.

---

My personal preference is to use PyInstaller since it was the easiest for me to get up and running, was designed to work nicely with various popular libraries such as numpy or pygame, and has great compatibility with various OSes and Python versions.

However, I've also successfully built various exes using cx_Freeze without too much difficulty, so you should also consider trying that program out.

I haven't yet had a chance to to try pynist, Nuitka, or Cython extensively, but they seem like pretty interesting and innovative solutions. If you run into trouble using the first group of programs, it might be worthwhile to try one of these three. Since they work fundamentally differently then the Pyinstaller/cx_freeze-style programs, they might succeed in those odd edge cases where the first group fails.

In particular, I think pynist is a good way of sidestepping the entire issue of distributing your code altogether: Macs and Linux already have native support for Python, and just installing Python on Windows might genuinely be the cleanest solution. (The downside is now that you need to worry about targeting multiple versions of Python + installing libraries).

Nuitka and Cython (in my limited experience) seem to work fairly well. Again, I haven't tested them extensively myself, and so my main observation is that they seem to take much longer to produce an exe then the "freeze" style programs do.

---

All this being said, converting your Python program into an executable isn't necessarily the only way of distributing your code. To learn more about what other options are available, see the following links:

• https://packaging.python.org/overview/#packaging-python-applications
• https://docs.python-guide.org/shipping/packaging/#for-linux-distributions

Solution 2

Better use pip install auto-py-to-exe which provides a beautiful UI with all options required to create an executable.

After installing just type auto-py-to-exe in your terminal or command prompt.

Solution 3

pyinstaller is still under active development. You can see the latest changes on GitHub.

It has support for all three major platforms:

• Windows (32-bit and 64-bit)
• Linux (32-bit and 64-bit)
• Mac OS X (32-bit and 64-bit)

and it supports Python versions 2.6 and 2.7. It does not support Python 3, but there is an experimental Python 3 branch.

Update

As of version 3.2.1 it supports Python 2.7, 3.3-3.5

Comments

[ShadowFlame]

I am still writing in 2.x(2.7.2 to be exact), but might see the need to transfer to 3.x(if modules and such are compatible) and would need a solution then too.

[ivan_pozdeev]

Note that packaging will complicate problem diagnostics greatly. Not only you (or pdb) don't have easy access to the files being executed, py2exe (dunno about the others) doesn't include .py files so you won't see source lines in stack traces.

[ShadowFlame]

Just as a point of interest, I've started using pyinstaller

[gaborous]

Note that you also need to include inside your bundle the Microsoft C++ Redistributables (aka msvcrxx.dll, where xx is a version number) to make the .exe run (or ask users to install it by themselves). This is necessary because Python is built on Windows using Visual Studio.

[Nelda.techspiress]

So it looks like none of the python IDE's (pycharm or pydev - eclipse pluggin) have yet to incorporate the compile-to-single-executable functionality into the IDE itself. Is that correct? :-)

[Martín De la Fuente]

If you care about keeping safe your source code, probably Cython is the best choice because it compiles C code. Those programs that use freezing technique generally can be easily decompiled.

[Tom]

PyInstaller is listed above as supporting Python 3.7. That is not true according to my experience and according to the description at pyinstaller.org, which states "PyInstaller works with Python 2.7 and 3.3—3.6".

[Michael0x2a]

@Tom -- After doing a little bit more digging, it looks like while pyinstaller itself does support Python 3.7, they haven't officially released a new version with 3.7 support. (E.g. their github repo states that they support Python 3.7 + they appear to have no open issues left related to 3.7, but the latest version of pyinstaller on PyPi is from Dec 2017). So if you need 3.7 support, you could try building + installing pyinstaller directly from source, or wait until the next release. (Or use another program, of course)

[Michael0x2a]

@Tom -- in case you care, the Pyinstaller team released a new version yesterday -- it supports Python 3.7, as predicted. The website is still out-of-date, but the latest version is out on pypi.

[Soutzikevich]

py2exe released a new version on 25th of October 2020 and it supports python 3.5 - 3.8 only.

[Wippo]

The provided link to cx_Freeze website is not working. Here is the new one