Complete CLI Reference

This is a full reference of the project’s command line tools, with the same information as you get from using the -h option. It is generated from source code and thus always up to date.

Available Commands

shiv

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

shiv [OPTIONS] [PIP_ARGS]...

Options

--version

Show the version and exit.

-e, --entry-point <entry_point>

The entry point to invoke (takes precedence over –console-script).

-c, --console-script <console_script>

The console_script to invoke.

-o, --output-file <output_file>

The path to the output file for shiv to create.

-p, --python <python>

The python interpreter to set as the shebang, a.k.a. whatever you want after ‘#!’ (default is ‘/usr/bin/env python3’)

--site-packages <site_packages>

The path to an existing site-packages directory to copy into the zipapp.

--build-id <build_id>

Use a custom build id instead of the default (a SHA256 hash of the contents of the build). Warning: must be unique per build!

--compressed, --uncompressed

Whether or not to compress your zip.

--compile-pyc

Whether or not to compile pyc files during initial bootstrap.

-E, --extend-pythonpath

Add the contents of the zipapp to PYTHONPATH (for subprocesses).

--reproducible

Generate a reproducible zipapp by overwriting all files timestamps to a default value. Timestamp can be overwritten by SOURCE_DATE_EPOCH env variable. Note: If SOURCE_DATE_EPOCH is set, this option will be implicitly set to true.

--no-modify

If specified, this modifies the runtime of the zipapp to raise a RuntimeException if the source files (in ~/.shiv or SHIV_ROOT) have been modified. It’s recommended to use Python’s “–check-hash-based-pycs always” option with this feature.

--preamble <preamble>

Provide a path to a preamble script that is invoked by shiv’s runtime after bootstrapping the environment, but before invoking your entry point.

--root <root>

Override the ‘root’ path (default is ~/.shiv).

Arguments

PIP_ARGS

Optional argument(s)

shiv-info

A simple utility to print debugging information about PYZ files created with shiv

shiv-info [OPTIONS] PYZ

Options

-j, --json

output as plain json

Arguments

PYZ

Required argument

Additional Hints

Choosing a Python Interpreter Path

A good overall interpreter path as passed into --python is /usr/bin/env python3. If you want to make sure your code runs on the Python version you tested it on, include the minor version (e.g. … python3.6) – use what fits your circumstances best.

On Windows, the Python launcher py knows how to handle shebangs using env, so it’s overall the best choice if you target multiple platforms with a pure Python zipapp.

Also note that you can always fix the shebang during installation of a zipapp using this:

python3 -m zipapp -p '/usr/bin/env python3.7' -o ~/bin/foo foo.pyz