Shiv API


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

Copy bootstrap code from shiv into the pyz.

This function is excluded from type checking due to the conditional import.

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.

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: str, 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: str) → None[source]

Write a shebang line.

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


shiv.pip.clean_pip_env() → Generator[[None, None], None][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(args: List[str]) → None[source]

pip install as a function.

Accepts a list of pip arguments.

>>> install(['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.

A function to vend the current zipfile, if any

shiv.bootstrap.extract_site_packages(archive, target_path, compile_pyc, compile_workers=0, force=False)[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[source]

Run a module in a scrubbed environment.

If a single pyz has multiple callers, we want to remove these vars as we no longer need them and they can cause subprocesses to fail with a ModuleNotFoundError.

Parameters:module (callable) – The entry point to invoke the pyz with.


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.