Last Updated on September 12, 2022

You can add support for multiprocessing when freezing your code via the multiprocessing.freeze_support() function.

In this tutorial you will discover how to add freeze support for multiprocessing in your Python program.

Let’s get started.

What is Freezing Code

You can package your code with a Python runtime.

For example, you can package your program up as a .exe for Windows or .app for macOS that includes both your program and all its code, as well as the Python runtime and relevant standard libraries required to execute it.

It allows your program to run without the end user having to install anything else, such as Python.

It requires that your code be transformed into C-code, called freezing, performed automatically by a freezing tool.

It converts Python byte code to C arrays; with a C compiler you can embed all your modules into a new program, which is then linked with the standard Python modules. […] It then compiles the generated C code and links it with the rest of the Python interpreter to form a self-contained binary which acts exactly like your script.

— How can I create a stand-alone binary from a Python script?

The benefit to the user is that your program will work out of the box with the intended version of Python. A downside is that the application will be much larger, e.g. megabytes, and required updates to the program or the included Python runtime will require an update of the entire package.

It is common to freeze end-user applications written in Python intended to be distributed on Windows and macOS, although frozen versions of a program can be distributed to all platforms.

Python includes a tool to freeze Python scripts called freeze.py.

Alternately, you can freeze your program and create a distribution of your application using a third-party tool, such as:

• py2exe: py2exe is a Python Distutils extension which converts Python scripts into executable Windows programs, able to run without requiring a Python installation.Spice.
• PyInstaller: PyInstaller bundles a Python application and all its dependencies into a single package. The user can run the packaged app without installing a Python interpreter or any modules.
• cx_Freeze: cx_Freeze creates standalone executables from Python scripts, with the same performance, is cross-platform and should work on any platform that Python itself works on.

Now that we know what freezing code means, let’s look at a possible problem when using multiprocessing.

Multiprocessing and Freezing Code

When a program is frozen in order to be distributed, some features of Python are not included or disabled by default.

This is for performance and/or security reasons.

One feature that is disabled when freezing a Python program is multiprocessing.

That is, we cannot create new python processes via multiprocessing.Process instances when freezing our program for distribution.

Creating a process in a frozen application results in a RuntimeError.

How can we use multiprocessing in frozen code?

Add Multiprocessing Support When Freezing Code

We can add support for multiprocessing in our program when freezing code via the multiprocessing.freeze_support() function.

Add support for when a program which uses multiprocessing has been frozen to produce a Windows executable. (Has been tested with py2exe, PyInstaller and cx_Freeze.)

— multiprocessing — Process-based parallelism

For example:

This function will allow a frozen program to create and start new processes via the multiprocessing.Process class when the program is frozen for distribution on Windows.

If the function is called and the program is not frozen for distribution, then it has no effect.

If the function is called on platforms other than Windows, it has no effect.

Calling freeze_support() has no effect when invoked on any operating system other than Windows. In addition, if the module is being run normally by the Python interpreter on Windows (the program has not been frozen), then freeze_support() has no effect.

— multiprocessing — Process-based parallelism

This function must be called as the first line of the program, e.g. the first line after protecting the entry point.

One needs to call this function straight after the if __name__ == ‘__main__’ line of the main module.

— multiprocessing — Process-based parallelism

For example:

Now that we know how to enable multiprocessing support in frozen code, let’s look at a worked example.

Example of Adding Freeze Support for Multiprocessing

We can add freeze support for multiprocessing.

In this example we will run a custom function in a child process. The main process will first add freeze support and then configure and start the child process.

First, we can define a function to run in a child process.

The function will report a message then sleep for two seconds.

The task() function below implements this.

Next, in the main process, we will first add support for multiprocessing while the program is frozen.

We can create and configure a new multiprocessing.Process instance to run our custom function.

Next, we can start the new child process, then wait for the child process to finish.

Tying this together, the complete example is listed below.

First, save the above program as a Python script with the filename “app.py“.

We can then freeze the program.

You can use your preferred freezing tool, such as a third-party tool or freeze.py.

In this case, we will use the freeze tool provided with Python. This is in the Tools/ directory of your Python installation and has the name freeze.py.

For example:

If you need help with this tool, see documentation in the Python Wiki.

• Freeze, Python Wiki.

To freeze our program, call the freeze.py tool and specify the name of our app.py script.

For example:

This will convert the program to C code.

Next, compile the C code.

This can be achieved by calling make.

Note, this assumes you have a C compiler and build system installed, which is typically the case by default for many modern development workstations, e.g. macOS and Linux.

For example:

This will compile the generated C-code into a binary for your platform.

Then run the program.

For example:

This will execute the native program.

Internally, the program will start a new child Python process and report a message.

You can learn more about multiprocessing in the tutorial:

• Multiprocessing in Python: The Complete Guide

Further Reading

This section provides additional resources that you may find helpful.

Python Multiprocessing Books

• Python Multiprocessing Jump-Start, Jason Brownlee (my book!)
• Multiprocessing API Interview Questions
• Multiprocessing API Cheat Sheet

I would also recommend specific chapters in the books:

• Effective Python, Brett Slatkin, 2019.
  • See: Chapter 7: Concurrency and Parallelism
• High Performance Python, Ian Ozsvald and Micha Gorelick, 2020.
  • See: Chapter 9: The multiprocessing Module
• Python in a Nutshell, Alex Martelli, et al., 2017.
  • See: Chapter: 14: Threads and Processes

Guides

• Python Multiprocessing: The Complete Guide
• Python Multiprocessing Pool: The Complete Guide
• Python ProcessPoolExecutor: The Complete Guide

APIs

• multiprocessing — Process-based parallelism
• PEP 371 - Addition of the multiprocessing package

References

• Thread (computing), Wikipedia.
• Process (computing), Wikipedia.

Takeaways

You now know how to add freeze support for multiprocessing in your Python program.

Do you have any questions?
Ask your questions in the comments below and I will do my best to answer.

Photo by Yves Alarie on Unsplash