Module Interface

The zipapp module will provide the following functions:

Command Line Usage

The zipapp module can be run with the python -m flag. The command line interface is as follows:

python -m zipapp directory [options]

    Create an archive from the given directory.  An archive will
    be created from the contents of that directory.  The archive
    will have the same name as the source directory with a .pyz
    extension.

    The following options can be specified:

    -o archive / --output archive

        The destination archive will have the specified name.  The
        given name will be used as written, so should include the
        ".pyz" or ".pyzw" extension.

    -p interpreter / --python interpreter

        The given interpreter will be written to the shebang line
        of the archive.  If this option is not given, the archive
        will have no shebang line.

    -m pkg.mod:fn / --main pkg.mod:fn

        The source directory must not have a __main__.py file. The
        archiver will write a __main__.py file into the target
        which calls fn from the module pkg.mod.

The behaviour of the command line interface matches that of zipapp.create_archive().

In addition, it is possible to use the command line interface to work with an existing archive:

python -m zipapp app.pyz --show

    Displays the shebang line of an archive.  Output is of the
    form

        Interpreter: /usr/bin/env
    or
        Interpreter: <none>

    and is intended for diagnostic use, not for scripts.

python -m zipapp app.pyz -o newapp.pyz [-p interpreter]

    Copy app.pyz to newapp.pyz, modifying the shebang line based
    on the -p option (as for creating an archive, no -p option
    means remove the shebang line).  Specifying a destination is
    mandatory.

    In-place modification of an archive is *not* supported, as the
    risk of damaging archives is too great for a simple tool.

As noted, the archives are standard zip files, and so can be unpacked using any standard ZIP utility or Python’s zipfile module. For this reason, no interfaces to list the contents of an archive, or unpack them, are provided or needed.

FAQ

Are you sure a standard ZIP utility can handle #! at the beginning?

Absolutely. The zipfile specification allows for arbitrary data to be prepended to a zipfile. This feature is commonly used by “self-extracting zip” programs. If your archive program can’t handle this, it is a bug in your archive program.

Isn’t zipapp just a very thin wrapper over the zipfile module?

Yes. If you prefer to build your own Python zip application archives using other tools, they will work just as well. The zipapp module is a convenience, nothing more.

Why not use just use a .zip or .py extension?

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

How does this compete with existing package formats?

The sdist, bdist and wheel formats are designed for packaging of modules to be installed into an existing Python installation. They are not intended to be used without installing. The executable zip format is specifically designed for standalone use, without needing to be installed. They are in effect a multi-file version of a standalone Python script.

Convenience Values for Shebang Lines

Is it worth having “convenience” forms for any of the common interpreter values? For example, -p 3 meaning the same as -p "/usr/bin/env python3". It would save a lot of typing for the common cases, as well as giving cross-platform options for people who don’t want or need to understand the intricacies of shebang handling on “other” platforms.

Downsides are that it’s not obvious how to translate the abbreviations. For example, should “3” mean “/usr/bin/env python3”, “/usr/bin/python3”, “python3”, or something else? Also, there is no obvious short form for the key case of “/usr/bin/env python” (any available version of Python), which could easily result in scripts being written with overly-restrictive shebang lines.

Overall, this seems like there are more problems than benefits, and as a result has been dropped from consideration.

Registering .pyz as a Media Type

It was suggested [3] that the .pyz extension should be registered in the Unix database of extensions. While it makes sense to do this as an equivalent of the Windows installer registering the extension, the .py extension is not listed in the media types database [4]. It doesn’t seem reasonable to register .pyz without .py, so this idea has been omitted from this PEP. An interested party could arrange for both .py and .pyz to be registered at a future date.

Default Interpreter

The initial draft of this PEP proposed using /usr/bin/env python as the default interpreter. Unix users have problems with this behaviour, as the default for the python command on many distributions is Python 2, and it is felt that this PEP should prefer Python 3 by default. However, using a command of python3 can result in unexpected behaviour for Windows users, where the default behaviour of the launcher for the command python is commonly customised by users, but the behaviour of python3 may not be modified to match.

As a result, the principle “in the face of ambiguity, refuse to guess” has been invoked, and archives have no shebang line unless explicitly requested. On Windows, the archives will still be run (with the default Python) by the launcher, and on Unix, the archives can be run by explicitly invoking the desired Python interpreter.

Command Line Tool to Manage Shebang Lines

It is conceivable that users would want to modify the shebang line for an existing archive, or even just display the current shebang line. This is tricky to do so with existing tools (zip programs typically ignore prepended data totally, and text editors can have trouble editing files containing binary data).

The zipapp module provides functions to handle the shebang line, but does not include a command line interface to that functionality. This is because it is not clear how to provide one without the resulting interface being over-complex and potentially confusing. Changing the shebang line is expected to be an uncommon requirement.