Shiv API


shiv.cli.copy_bootstrap(bootstrap_target: pathlib.Path) → None[source]

Copy bootstrap code from shiv into the pyz.

Parameters:bootstrap_target – The temporary directory where we are staging pyz contents.
shiv.cli.find_entry_point(site_packages: pathlib.Path, console_script: str) → str[source]

Find a console_script in a site-packages directory.

Console script metadata is stored in entry_points.txt per setuptools convention. This function searches all entry_points.txt files and returns the import string for a given console_script argument.

  • site_packages – A path to a site-packages directory on disk.
  • console_script – A console_script string.
shiv.cli.validate_interpreter(interpreter_path: Union[str, NoneType] = None) → pathlib.Path[source]

Ensure that the interpreter is a real path, not a symlink.

If no interpreter is given, default to sys.exectuable

Parameters:interpreter_path – A path to a Python interpreter.

constants —

This module contains various error messages.


This module is a slightly modified implementation of Python’s “zipapp” module.

We’ve copied a lot of zipapp’s code here in order to backport support for compression.

shiv.builder.create_archive(source: pathlib.Path, target: pathlib.Path, interpreter: pathlib.Path, main: str, compressed: bool = True) → None[source]

Create an application archive from SOURCE.

A slightly modified version of stdlib’s zipapp.create_archive

shiv.builder.write_file_prefix(f: IO[Any], interpreter_path: pathlib.Path) → None[source]

Write a shebang line.


Shiv explicitly uses -sE as start up flags to prevent contamination of sys.path.

  • f – An open file handle.
  • interpreter_path – A path to a python interpreter.


shiv.pip.clean_pip_env() → Generator[[NoneType, NoneType], NoneType][source]

A context manager for temporarily removing ‘PIP_REQUIRE_VIRTUALENV’ from the environment.

Since shiv installs via –target, we need to ignore venv requirements if they exist.

shiv.pip.install(interpreter_path: str, args: List[str]) → None[source]

pip install as a function.

Accepts a list of pip arguments.

>>> install('/usr/local/bin/python3', ['numpy', '--target', 'site-packages'])
Collecting numpy
Downloading numpy-1.13.3-cp35-cp35m-manylinux1_x86_64.whl (16.9MB)
    100% || 16.9MB 53kB/s
Installing collected packages: numpy
Successfully installed numpy-1.13.3



Actually bootstrap our shiv environment.

shiv.bootstrap.cache_path(archive, root_dir, build_id)[source]

Returns a ~/.shiv cache directory for unzipping site-packages during bootstrap.

  • archive (ZipFile) – The zipfile object we are bootstrapping from.
  • buidl_id (str) – The build id generated at zip creation.
shiv.bootstrap.extract_site_packages(archive, target_path)[source]

Extract everything in site-packages to a specified path.

  • archive (ZipFile) – The zipfile object we are bootstrapping from.
  • target_path (Path) – The path to extract our zip to.

Returns a callable for a given setuptools style import string

Parameters:import_name – A console_scripts style import string



A function to vend the current zipfile, if any


This module contains the Environment object, which combines settings decided at build time with overrides defined at runtime (via environment variables).


The code in this module is adapted from

It is used to enter an interactive interpreter session from an executable created with shiv.