Python's zipapp: Build Executable Zip Applications – Real Python

• Setting Up a Python Zip Application

• Conclusion

• What a Python Zip application is

• How Zip applications work internally

• How to build Python Zip applications with zipapp

• What standalone Python Zip apps are and how to create them

• How to create Python Zip apps manually using command-line tools

Getting Started With Python Zip Applications

What Is 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

• 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

Why Use Python Zip Applications?

How Do I Build a Python Zip Application?

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.

Setting Up a Python Zip Application

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

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

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

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

(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
    ...

(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.
    ...

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

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

Building a Python Zip Application With zipapp

Using zipapp From the Command Line

$ 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()

Using zipapp From Python Code

>>> import zipapp

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

• 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.

Running a Python Zip Application

(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
    ...

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
    ...

$ 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
    ...

Creating a Standalone Python Zip App With zipapp

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

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

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

Creating a Python Zip Application Manually

Using Python’s zipfile

# 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)

Using Unix Command-Line Tools

$ 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

(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.
    ...

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

(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!
    ...

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

Conclusion

• 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