Improving Python ZIP Application Support

PEP: 441
Title: Improving Python ZIP Application Support
Version: c930e4ebf844
Last-Modified: 2013-04-10 09:30:46 +0200 (Wed, 10 Apr 2013)
Author: Daniel Holth <dholth at>
Status: Draft
Type: Standards Track
Created: 30 March 2013
Post-History: 30 March 2013, 1 April 2013

Improving Python ZIP Application Support

Python has had the ability to execute directories or ZIP-format archives as scripts since version 2.6 [1] . When invoked with a zip file or directory as its first argument the interpreter adds that directory to sys.path and executes the __main__ module. These archives provide a great way to publish software that needs to be distributed as a single file script but is complex enough to need to be written as a collection of modules.

This feature is not as popular as it should be mainly because no one’s heard of it as it wasn’t promoted as part of Python 2.6 [2] , but also because Windows users don’t have a file extension (other than .py) to associate with the launcher.

This PEP proposes to fix these problems by re-publicising the feature, defining the .pyz and .pyzw extensions as “Python ZIP Applications” and “Windowed Python ZIP Applications”, and providing some simple tooling to manage the format.

A New Python ZIP Application Extension

The Python 3.4 installer will associate .pyz and .pyzw “Python ZIP Applications” with the platform launcher so they can be executed. A .pyz archive is a console application and a .pyzw archive is a windowed application, indicating whether the console should appear when running the app.

Why not use .zip or .py? Users expect a .zip file would be opened with an archive tool, and users expect .py to contain text. Both would be confusing for this use case.

For UNIX users, .pyz applications should be prefixed with a #! line pointing to the correct Python interpreter and an optional explanation:

#!/usr/bin/env python3
# This is a Python application stored in a ZIP archive, created with
# pyzaa.
(binary contents of archive)

As background, ZIP archives are defined with a footer containing relative offsets from the end of the file. They remain valid when concatenated to the end of any other file. This feature is completely standard and is how self-extracting ZIP archives and the bdist_wininst installer format work.

Minimal Tooling: The pyzaa Module

This PEP also proposes including a simple application for working with these archives: The Python Zip Application Archiver “pyzaa” (rhymes with “huzzah” or “pizza”). “pyzaa” can archive these files, compile bytecode, and can write the __main__ module if it is not present.


python -m pyzaa (pack | compile)

python -m pyzaa pack [-o path/name] [-m module.submodule:callable] [-c] [-w] [-p interpreter] directory :

ZIP the contents of directory as directory.pyz or [-w]
directory.pyzw. Adds the executable flag to the archive.

``-c`` compile .pyc files and add them to the archive

``-p interpreter`` include #!interpreter as the first line of the archive

``-o path/name`` archive is written to path/name.pyz[w] instead of
dirname. The extension is added if not specified.

``-m module.submodule:callable`` is written as “import
module.submodule; module.submodule.callable()”

pyzaa pack will warn if the directory contains C extensions or if
it doesn’t contain

python -m pyzaa compile arcname.pyz[w] :

The Python files in arcname.pyz[w] are compiled and appended to the
ZIP file.

A standard ZIP utility or Python’s zipfile module can unpack the archives.


  1. Are you sure a standard ZIP utility can handle #! at the beginning?
  1. Absolutely. If it doesn't, it is a bug in your archive program.
  1. Isn’t pyzaa just a very thin wrapper over zipfile and compileall?
  1. Yes.
  1. How does this compete with existing sdist/bdist formats?

A. There is some overlap, but .pyz files are especially interesting as a way to distribute an installer. They may also prove useful as a way to deliver applications when users shouldn’t be asked to perform virtualenv + “pip install”.


[1] “Allow interpreter to execute a zip file” ( )
[2] “Feature is not documented” ( )

Notice: While Javascript is not essential for this website, your interaction with the content will be limited. Please turn Javascript on for the full experience.