Python's zipapp: Build Executable Zip Applications

Getting Started With Python Zip Applications

One of the most challenging problems in the Python ecosystem is finding an effective way to distribute executable applications, such as graphical user interface (GUI) and command-line interface (CLI) programs.

Compiled programming languages, such as C, C++, and Go, can generate executable files that you can run directly on different operating systems and architectures. This ability makes it easy for you to distribute software to your end users.

However, Python doesn’t work like that. Python is an interpreted language, which means that you need a suitable Python interpreter to run your applications. There’s no direct way to generate a standalone executable file that doesn’t need an interpreter to run.

There are many solutions out there that aim to solve this issue. You’ll find tools such as PyInstaller, py2exe, py2app, Nuitka, and more. Those tools allow you to create self-contained executable applications that you can distribute to your end users. However, setting these tools up can be a complex and challenging process.

Sometimes you don’t need that extra complexity. You just need to build an executable app from a script or a small program so that you can distribute it to your end users quickly. If your application is small enough and uses pure Python code, then you can be well-served with a Python Zip application.

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

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

$ python ./hello.zip
Hello, World!

#!/usr/bin/env python3

Setting Up a Python Zip Application

Up to this point, you’ve learned what Python Zip applications are, how to structure them, why to use them, and what steps you need to follow when creating them. You’re ready to start building your own. First, though, you need to have a functional application or script to use for your Python Zip app.

For this tutorial, you’ll use a sample application called reader, which is a minimal web feed reader that reads the latest articles and resources from the Real Python feed.

To follow along, you should clone the repository of reader into your local machine. Open your command line in a working directory of your choice and run the following command:

$ git clone https://github.com/realpython/reader.git

This command downloads the full contents of the reader repository into a reader/ folder in your current directory.

Once you’ve cloned the repository, you need to install the application’s dependencies. First, you should create a Python virtual environment. Go ahead and run the following commands:

$ cd reader/
$ python3 -m venv ./venv
$ source venv/bin/activate

These commands create and activate a new Python virtual environment in the reader/ directory, which is the root directory of the reader project.

C:\> python -m venv venv
C:\> venv\Scripts\activate.bat

Now you can install the dependencies of reader using pip:

(venv) $ python -m pip install feedparser html2text importlib_resources

Running the command above will install all the application’s dependencies in your active Python virtual environment.

Here’s an example of using reader to get a list of the latest articles, courses, podcast episodes, and other learning resources from Real Python:

(venv) $ python -m reader
The latest tutorials from Real Python (https://realpython.com/)
  0 The Django Template Language: Tags and Filters
  1 Pass by Reference in Python: Best Practices
  2 Using the "and" Boolean Operator in Python
    ...

This output will be different for you since reader lists the thirty latest learning resources in the feed. Each learning resource has an ID number. To get the contents of one item out of these learning resources, you can pass the corresponding ID number as a command-line argument to reader:

(venv) $ python -m reader 2
Using the "and" Boolean Operator in Python

Python has three Boolean operators, or **logical operators** : `and`, `or`,
and `not`. You can use them to check if certain conditions are met before
deciding the execution path your programs will follow. In this tutorial,
you'll learn about the `and` operator and how to use it in your code.
    ...

This command prints part of the contents of the article Using the “and” Boolean Operator in Python to your screen using the Markdown text format. You can read any of the available pieces of content by changing the ID number.

To create a Zip application from the reader repository, you’ll mainly use the reader/ folder. This folder has the following structure:

reader/
|
├── config.cfg
├── feed.py
├── __init__.py
├── __main__.py
└── viewer.py

The most significant fact to note from the reader/ directory is that it includes a __main__.py file. This file enables you to execute the package using the python -m reader command as you did before.

Having a __main__.py file provides the required entry-point script to create a Python Zip application. In this example, the __main__.py file is inside the reader package. If you create your Zip application using this directory structure, then your app won’t run because __main__.py won’t be able to import objects from reader.

To work around this, copy the reader package to an external directory called realpython/ and place the __main__.py file at its root. Then remove the __pycache__/ folder that results from running python -m reader, which you did before. You should end up with the following directory structure:

realpython/
│
├── reader/
│   ├── __init__.py
│   ├── config.cfg
│   ├── feed.py
│   └── viewer.py
│
└── __main__.py

With this new directory structure, you’re ready to create your first Python Zip application with zipapp. That’s what you’ll do in the following section.

Building a Python Zip Application With zipapp

To create your first Python Zip application, you’ll use zipapp. This module implements a user-friendly command-line interface that provides the required options for you to build a full-fledged Zip application with a single command. You can also use zipapp from your code through the module’s Python API, which mainly consists of a single function.

In the following two sections, you’ll learn about both approaches to building Zip applications using zipapp.

$ python -m zipapp <source> [OPTIONS]

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

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

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

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

>>> import zipapp

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

Running a Python Zip Application

So far, you’ve learned how to create Python Zip applications using zipapp from the command line and Python code. Now it’s time to run your realpython.pyz app to make sure it works.

If you’re on a Unix-like system, then you can run your application by executing the following:

(venv) $ ./realpython.pyz
The latest tutorials from Real Python (https://realpython.com/)
  0 The Django Template Language: Tags and Filters
  1 Pass by Reference in Python: Best Practices
  2 Using the "and" Boolean Operator in Python
    ...

Cool! It works! Now you have a single application file that you can quickly share with friends and colleagues.

You don’t need to invoke Python to run the application from the command line anymore. Since your Zip application archive has a shebang line at the beginning, the operating system will automatically use your active Python interpreter to run the contents of the target archive.

If you’re on Windows, then your Python installation should have registered .pyz and .pyzw files and should be able to run them:

C:\> .\realpython.pyz
The latest tutorials from Real Python (https://realpython.com/)
  0 The Django Template Language: Tags and Filters
  1 Pass by Reference in Python: Best Practices
  2 Using the "and" Boolean Operator in Python
    ...

The reader application you’re using in this tutorial has a command-line interface, so it makes sense to run it from the command line or terminal window. However, if you have a GUI application, then you’ll be able to run it from your favorite file manager as you usually run executable apps.

Again, you can execute any Zip application by invoking the appropriate Python interpreter with the application’s filename as an argument:

$ python3 realpython.pyz
The latest tutorials from Real Python (https://realpython.com/)
  0 The Django Template Language: Tags and Filters
  1 Pass by Reference in Python: Best Practices
  2 Using the "and" Boolean Operator in Python
    ...

In this example, you use the system Python 3.x installation to run realpython.pyz. If you have many Python versions on your system, then you may need to be more specific and use a command like python3.9 realpython.pyz.

Note that whatever interpreter you use, you need to have the application’s dependencies installed. Otherwise, your application will fail. Having unsatisfied dependencies is a common issue with Python Zip applications. To work around this annoying situation, you can create a standalone application, which is the topic of the following section.

Creating a Standalone Python Zip App With zipapp

You can also use zipapp to create self-contained or standalone Python Zip applications. This type of application bundles all its dependencies into the app’s ZIP file. This way, your end users only need a suitable Python interpreter for running the application. They don’t need to worry about dependencies.

To create a standalone Python Zip application, you first need to install its dependencies into the source directory using pip. Go ahead and create a copy of your realpython/ directory with the name realpython_sa/. Then run the following command to install the app’s dependencies:

(venv) $ python -m pip install feedparser html2text importlib_resources \
--target realpython_sa/

This command installs all the dependencies of reader using pip install with the --target option. The documentation of pip says that this option allows you to install packages into a target directory. In this example, that directory must be your app’s source directory, realpython_sa/.

(venv) $ python -m pip install \
-r requirements.txt \
--target app_directory/

Once you’ve installed the dependencies of reader into realpython_sa/, you can optionally remove the *.dist-info directories that pip creates. These directories contain several files with metadata that pip uses to manage the corresponding package. Since you don’t need that information any longer, you can get rid of it.

The final step in the process is to build the Zip application using zipapp as usual:

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

This command produces a standalone Python Zip application in realpython_sa.pyz. To run this application, your end users just need to have a proper Python 3 interpreter on their machine. The advantage of this kind of application compared to a regular Zip application is that your end users don’t need to install any dependencies to run the application. Go ahead and give it a try!

In the example above, you use the -c option of zipapp to compress the contents of realpython_sa/. This option can be fairly convenient for applications with many dependencies that take a significant amount of disk space.

Creating a Python Zip Application Manually

As you’ve already learned, zipapp has been available in the standard library since Python 3.5. If you’re using a Python version lower than that, then you can still build your Python Zip applications manually without the need for zipapp.

In the following two sections, you’ll learn how to create a Zip application using zipfile from the Python standard library. You’ll also learn how to use some command-line tools to achieve the same task.

# build_app.py

import pathlib
import stat
import zipfile

app_source = pathlib.Path("realpython/")
app_filename = pathlib.Path("realpython.pyz")

with open(app_filename, "wb") as app_file:
    # 1. Prepend a shebang line
    shebang_line = b"#!/usr/bin/env python3\n"
    app_file.write(shebang_line)

    # 2. Zip the app's source
    with zipfile.ZipFile(app_file, "w") as zip_app:
        for file in app_source.rglob("*"):
            member_file = file.relative_to(app_source)
            zip_app.write(file, member_file)

# 3. Make the app executable (POSIX systems only)
current_mode = app_filename.stat().st_mode
exec_mode = stat.S_IEXEC
app_filename.chmod(current_mode | exec_mode)

$ cd realpython/
$ zip -r ../realpython.zip *

$ python -m zipfile --create realpython.zip realpython/*

$ cd ..
$ echo '#!/usr/bin/env python3' | cat - realpython.zip > realpython.pyz

$ chmod +x realpython.pyz

Using Third-Party Tools to Create Python Apps

In the Python ecosystem, you’ll find a few third-party libraries that work similarly to zipapp. They provide many more features and can be useful to explore. In this section, you’ll learn about two of these third-party libraries: pex and shiv.

The pex project provides a tool to create PEX files. PEX stands for Python executable and is a file format that stores self-contained executable Python virtual environments. The pex tool packs these environments into ZIP files with a shebang line and a __main__.py module, which allows you to execute the resulting PEX file directly. The pex tool is an expansion on the ideas outlined in PEP 441.

To create an executable application with pex, you first need to install it:

(venv) $ python -m pip install pex
(venv) $ pex --help
pex [-o OUTPUT.PEX] [options] [-- arg1 arg2 ...]

pex builds a PEX (Python Executable) file based on the given specifications:
sources, requirements, their dependencies and other options.
Command-line options can be provided in one or more files by prefixing the
filenames with an @ symbol. These files must contain one argument per line.
    ...

The pex tool provides a rich set of options that allows you to fine-tune your PEX files. The following command shows how to create a PEX file for the reader project:

(venv) $ pex realpython-reader -c realpython -o realpython.pex

This command creates realpython.pex in your current directory. This file is a Python executable for reader. Note that pex handles the installations of reader and all its dependencies from PyPI. The reader project is available on PyPI with the name realpython-reader, which is why you use that name as the first argument to pex.

The -c option allows you to define which console script the application will use. In this case, the console script is realpython as defined in the setup.py file of reader. The -o option specifies the output file. As usual, you can execute ./realpython.pex from your command line to run the application.

Since the contents of the .pex file are unzipped before execution, PEX applications solve the limitation of zipapp applications and allow you to execute code from .pyd, .so, and .dll files.

A final detail to note is that pex creates and packs a Python virtual environment in the resulting PEX file. This behavior makes your Zip application a lot bigger than a regular app created with zipapp.

The second tool you’ll learn about in this section is shiv. It’s a command-line utility for building self-contained Python Zip applications as described in PEP 441. The advantage of shiv compared to zipapp is that shiv automatically includes all of the app’s dependencies in the final archive and makes them available in Python’s module search path.

To use shiv, you need to install it from PyPI:

(venv) $ python -m pip install shiv
(venv) $ shiv --help
Usage: shiv [OPTIONS] [PIP_ARGS]...

  Shiv is a command line utility for building fully self-contained Python
  zipapps as outlined in PEP 441, but with all their dependencies included!
    ...

The --help option shows a complete usage message that you can check for a quick understanding of how shiv works.

To build a Python Zip application with shiv, you need an installable Python application with a setup.py or pyproject.toml file. Fortunately, the original reader project from GitHub fulfills this requirement. Go back to the directory containing the cloned reader/ folder and run the following command:

(venv) $ shiv -c realpython \
-o realpython.pyz reader/ \
-p "/usr/bin/env python3"

Like the pex tool, shiv has a -c option to define a console script for the application. The -o and -p options allow you to provide an output filename and a proper Python interpreter, respectively.

Unlike zipapp, shiv enables you to use the .pyd, .so, and .dll files you store in the application’s archive. To do so, shiv includes a special bootstrap function within the archive. This function unpacks the application’s dependencies into a .shiv/ directory in your home folder and adds them to Python’s sys.path.

This feature allows you to create standalone applications that include libraries that are partially written in C and C++ for speed and efficiency, such as NumPy.

Conclusion

Having a quick and efficient way to distribute your Python executable applications can make the difference in satisfying your end users’ needs. Python Zip applications provide an effective and accessible solution for you to bundle and distribute ready-to-run applications. You can use zipapp from the Python standard library to quickly create your own executable Zip applications and pass them along to your end users.

In this tutorial, you learned:

• What a Python Zip application is
• How Zip applications work internally
• How to build your own Python Zip applications with zipapp
• What standalone Zip apps are and how to create them using pip and zipapp
• How to create Python Zip applications manually using command-line tools

With this knowledge, you’re ready to quickly create Python Zip applications as a convenient way to distribute your Python programs and scripts to your end users.