How to Compile Python scripts to executables (Py2exe, Py2app and PyInstaller)

For every new learner, it is normal to want to share your projects amongst friends so they can use that amazing thing that you’ve built. However, we can’t assume all our friends are tech-savvy and give them your scripts to run. So, in this article, I’ll be highlighting how to compile your Python scripts into executables(applications) that run on Windows and macOS.

When your python program is created, compiling its script is done in three major steps:

1. Install your compiler package.
2. Create your setup script (e.g setup.py).
3. Run your setup script with the compiler’s commands.

If you complete these steps properly, your app should be up and running well.

How to compile Python Scripts with Py2exe for Windows

Py2exe is a very common python compiler package for windows. To install py2exe in your project's environment, run the command:

pip install py2exe

Now that you have py2exe installed, you can create the setup.py script:

from distutils.core import setup
import py2exe
setup(console = ['myscript.py'])

However, when working with a GUI, we would replace console with windows.

For instance, we have the following script test.py:

print ("This is a test program\n")
user = input("What is your name?\n")
print ("Hi there! " + user)

Then, we have our setup script as:

from distutils.core import setup
import py2exe

setup(console = ['test.py'])

Once we have our python and setup script ready, using the terminal, we can now run the following command in the same directory where our python and setup scripts are.

python setup.py py2exe

Running this command initializes py2exe and it creates a new dist folder containing all the files required to run the python script. Since the files are a lot and quite confusing sometimes, to bundle these files, we can add these few lines to our setup.py script.

from distutils.core import setup
import py2exe

setup(
      options = {'py2exe': {'bundle_files' : 1, 'compressed': True}},
      console = [{'script': "test.py"}],
      zipfile = None,
     )

Now you can re-initialize py2exe in the project’s environment. When the dist folder is created, we can see how the files have been bundled into fewer files.

We have simply created an application for windows but you should take note that the executable cannot work if taken out of the dist folder. Also, py2exe is specifically made for Windows but to compile scripts to applications for macOS, we can use Py2app.

How to compile Python Scripts with Py2app for MacOS

Py2app is another python compiler package but specifically for macOS. To install py2app in your project environment, run the command:

pip install py2app

Now that we have py2app installed, we can create the setup.py script:

from setuptools import setup
APP = ['main.py']
OPTIONS = {} 
setup( 
      app = APP,
      options = {"py2app": OPTIONS},
      setup_requires = ["py2app"],
     )

With the python and setup script ready, using the terminal, we can now run the following command in the same directory where our python and setup scripts are.

python setup.py py2app

However, py2app works best with GUI programs. If we have a script test.py (that should be run in the terminal) like:

print ("This is a test program\n")
user = input("What is your name?\n")
print ("Hi there! " + user)

Then, we have our setup.py script as:

from setuptools import setup
APP = ['main.py']
OPTIONS = {} 
setup( 
      app = APP,
      options = {"py2app": OPTIONS},
      setup_requires["py2app"],
     )

When we initialize and run the setup script using:

python setup.py py2app

It creates a new dist folder that contains the app, and a build folder containing all the files required to run the python script.

If we run the program directly from its folder, it gives an app Error. So, to run a non-window script like test.py in our IDE, we can locate the app in the dist folder by going from:

dist > MacOS > app (where app is the name of your program).

We can simply copy the path of the “app” and run that in the terminal and our program should work fine.

Now that we can create applications for specific Operating Systems, there might be cases where you want to create an executable for different platforms.

How to compile Python Scripts with PyInstaller

PyInstaller is one of the most commonly used because it is a cross-platform compiler (ie, it works for both Windows, macOS, or Linux).

To get started, install the PyInstaller package in the environment where your project is by running the command:

pip install pyinstaller

To ensure you’ve successfully installed it, you can run the following command to see the version installed:

pyinstaller --version

Unlike py2exe and py2app, PyInstaller does not require a setup script. Now that you have PyInstaller installed, in the same environment or directory where your file is, run the command:

pyinstaller myscript.py

This is the simplest use case where myscript.py is your python program.

The general syntax of the PyInstaller command is:

pyinstaller [options] script

With PyInstaller, you can specify different options alongside your python script such as —-onedir or —-onefile.

By default, pyinstaller uses the option —-onedir (also written as -D) to create a one-folder bundle containing an executable. However, when you move the executable out of the folder, it no longer works. To solve this problem, creating a shortcut of the executable and distributing the shortcut works fine. This way, the executable remains in its parent folder.

On the other hand, using —-onefile or -F creates a one-file bundled executable, which is relatively larger and takes more time to load compared to the executable from the —-onedir folder.

How does PyInstaller work?

When you run the command, PyInstaller analyzes myscript.py and then creates a .spec file in the same folder as your script. A .spec file contains the information given by the options that were specified when PyInstaller was run.

The .spec file is created alongside the build and dist folders. The build folder is home for the log files and working files written by pyinstaller while the dist folder comprises the bundled app for you to distribute.

In cases where your python program is a GUI, we can use the option —-windowed which supports only Windows and macOS. Now, the command to initialize PyInstaller should look like this:

pyinstaller --onefile --windowed main.py

To learn more about PyInstaller and its various options, you can check out the docs as it is a well-documented source.

Conclusion

In this article, I have highlighted two major ways for you to create applications from your python scripts; for Specific OS and Cross-Platforms. Now, you should be able to compile your python programs and share them with your friends and everyone so the world can enjoy the amazing things you’ve built.