Python's zipapp: Build Executable Zip Applications

What Is a Python Zip Application?

PEP 441 – Improving Python ZIP Application Support formalized the idea, terminology, and specification around Python Zip applications. This type of application consists of a single file that uses the ZIP file format and contains code that Python can execute as a program. These applications rely on Python’s ability to run code from ZIP files that have a __main__.py module at their root, which works as an entry-point script.

Python has been able to run scripts from ZIP files since versions 2.6 and 3.0. The steps to achieve that are pretty straightforward. You just need a ZIP file with a __main__.py module at its root. You can then pass that file to Python, which adds it to sys.path and executes __main__.py as a program. Having the application’s archive in sys.path allows you to access its code through Python’s import system.

As a quick example of how all that works, say you’re on a Unix-like operating system, such as Linux or macOS, and you run the following commands:

$ echo 'print("Hello, World!")' > __main__.py

$ zip hello.zip __main__.py
  adding: __main__.py (stored 0%)

$ python ./hello.zip
Hello, World!

You use the echo command to create a __main__.py file containing the code print("Hello, World!"). Then you use the zip command to archive __main__.py into hello.zip. Once you’ve done that, you can run hello.zip as a program by passing the filename as an argument to the python command.

To round up the internal structure of Python Zip applications, you need a way to tell the operating system how to execute them. The ZIP file format allows you to prepend arbitrary data at the beginning of a ZIP archive. Python Zip applications take advantage of that feature to include a standard Unix shebang line in the application’s archive:

#!/usr/bin/env python3

On Unix systems, this line tells the operating system which program to use for executing the file at hand so that you can run the file directly without the python command. On Windows systems, the Python launcher properly understands the shebang line and runs the Zip application for you.

Even with a shebang line, you can always execute a Python Zip application by passing the application’s filename as an argument to the python command.

In summary, to build a Python Zip application, you need:

• An archive that uses the standard ZIP file format and contains a __main__.py module at its root
• An optional shebang line that specifies the appropriate Python interpreter to run the application

Besides the __main__.py module, your application’s ZIP file can contain Python modules and packages and any other arbitrary files. However, only .py, .pyc, and .pyo files are available for direct use through the import system. In other words, you can pack .pyd, .so, and .dll files in your application’s file but you won’t be able to use them unless you unzip them into your file system.

PEP 441 proposed .pyz and .pyzw as file extensions for Python Zip applications. The .pyz extension identifies console or command-line applications, while the .pyzw extension refers to windowed or GUI applications.

On Unix systems, you can remove the .pyz extension if you prefer a plain command name for your CLI applications. On Windows, the .pyz and .pyzw files are executable files because the Python interpreter registers them as such.

Why Use Python Zip Applications?

Say you have a program that your team uses a lot for their internal workflow. The program has grown beyond a single-file script into a full-fledged application with multiple packages, modules, and files.

At this point, some team members struggle to install and set up every new version. They keep asking you for a faster and easier way to set up and run the program. In that situation, you should consider creating a Python Zip application to bundle your program into a single file and distribute it as a ready-to-run app to your coworkers.

Python Zip applications are an excellent option for publishing software that you must distribute as a single executable file. It’s also a handy way to distribute software using informal channels, such as sending it through a computer network or hosting it on an FTP server.

Python Zip applications are convenient and quick ways to package and distribute Python applications in a ready-to-run format that can make your end user’s life much more pleasant.

How Do I Build a Python Zip Application?

As you’ve already learned, a Python Zip application consists of a standard ZIP file containing a __main__.py module, which works as the application’s entry point. When you run the application, Python automatically adds its container (the ZIP file itself) to sys.path so that __main__.py can import objects from the modules and packages shaping the application.

To build a Python Zip application, you can run the following general steps:

1. Create the application’s source directory containing a __main__.py module.
2. Zip the application’s source directory.
3. Add an optional Unix shebang line to define the interpreter for running the application.
4. Make the application’s ZIP file executable. This step applies to Unix-like operating systems only.

These steps are pretty straightforward and quick to run. With them, you can build a Python Zip application manually in a couple of minutes if you have the required tools and knowledge. However, the Python standard library includes a more convenient and faster solution for you.

PEP 441 proposed the addition of a new module called zipapp to the standard library. This module facilitates the creation of Zip applications, and it’s been available since Python 3.5.

In this tutorial, you’ll focus on creating Python Zip applications using zipapp. However, you’ll also learn how to run the whole series of steps manually using different tools. This additional knowledge can help you understand the entire process of creating Python Zip applications more deeply. It’ll also be helpful if you’re using a Python version lower than 3.5.

Using zipapp From the Command Line

The command-line interface of zipapp streamlines the process of packing Python applications into ZIP files. Internally, zipapp creates a Zip application from the source code by running the steps you learned before.

To run zipapp from the command line, you should use the following command syntax:

$ python -m zipapp <source> [OPTIONS]

If source is a directory, then this command creates a Zip application from that directory’s contents. If source is a file, then that file should be a ZIP file containing the application’s code. The contents of the input ZIP file are then copied to the target application archive.

Here’s a summary of the command-line options that zipapp accepts:

This table provides a minimal description of the command-line options for zipapp. For further details on specific behaviors of each option, check out the official documentation.

Now that you know the basics of using zipapp from the command line, it’s time to build the reader Zip application. Go back to your terminal window and run the following command:

(venv) $ python -m zipapp realpython/ \
-o realpython.pyz \
-p "/usr/bin/env python3"

In this command, you set the realpython/ directory as the source for your Zip application. With the -o option, you provide a name for the application’s archive, realpython.pyz. Finally, the -p option lets you set the interpreter that zipapp will use to build the shebang line.

That’s it! Now you’ll have a realpython.pyz file in your current directory. You’ll learn how to execute that file in a moment.

To showcase the -m and --main command-line options of zipapp, say you decide to change the reader project layout and rename __main__.py to cli.py while moving the file back to the reader package. Go ahead and create a copy of your realpython/ directory and make the suggested changes. After that, the copy of realpython/ should look like this:

realpython_copy/
│
└── reader/
    ├── __init__.py
    ├── cli.py
    ├── config.cfg
    ├── feed.py
    └── viewer.py

At the moment, your application’s source directory doesn’t have a __main__.py module. The -m command-line option of zipapp allows you to generate it automatically:

$ python -m zipapp realpython_copy/ \
-o realpython.pyz \
-p "/usr/bin/env python3" \
-m "reader.cli:main"

This command takes the -m option with "reader.cli:main" as an argument. This input value tells zipapp that the entry-point callable for the Zip application is main() from the cli.py module in the reader package.

The resulting __main__.py file has the following contents:

# -*- coding: utf-8 -*-
import reader.cli
reader.cli.main()

This __main__.py file is then packaged, along with your application’s source, into a ZIP archive named realpython.pyz.

Using zipapp From Python Code

Python’s zipapp also has an application programming interface (API) that you can use from your Python code. This API mostly consists of a function called create_archive(). With this function, you can create a Python Zip application quickly:

>>> import zipapp

>>> zipapp.create_archive(
...     source="realpython/",
...     target="realpython.pyz",
...     interpreter="/usr/bin/env python3",
... )

This call to create_archive() takes a first argument called source that represents the source of your Zip application. The second argument, target, holds the filename for the app’s archive. Finally, interpreter holds the interpreter to build and add as the shebang line to the app’s ZIP archive.

Here’s a summary of the arguments that create_archive() can take:

• source can take the following objects:
  • A string-based path to an existing source directory
  • A path-like object referring to an existing source directory
  • A string-based path to an existing Zip application archive
  • A path-like object referring to an existing Zip application archive
  • A file-like object opened for reading and pointing to an existing Zip application archive
• target accepts the following objects:
  • A string-based path to the target Zip application file
  • A path-like object to the target Zip application file
• interpreter specifies a Python interpreter, which is written as a shebang line at the beginning of the resulting application archive. Omitting this argument results in no shebang line and no execution permission for the application.
• main specifies the name of the callable that zipapp will use as the entry point for the target archive. You provide a value for main when you don’t have a __main__.py file.
• filter takes a Boolean-valued function that should return True if a given file in the source directory should be added to the final Zip application file.
• compressed accepts a Boolean value that determines whether you want to compress the source files or not.

Most of these arguments have an equivalent option in the command-line interface of zipapp. The example above uses just the first three arguments. Depending on your specific needs, you might use other arguments as well.