Skip to main content
Version: 2.5 (deprecated)

pex_binary

A Python target that can be converted into an executable PEX file.

PEX files are self-contained executable files that contain a complete Python environment capable of running the target. For more information, see (https://www.pantsbuild.org/v2.5/docs/pex-files).

Backend: ``

entry_point​

str
required

The entry point for the binary, i.e. what gets run when executing ./my_binary.pex.

You can specify a full module like 'path.to.module' and 'path.to.module:func', or use a shorthand to specify a file name, using the same syntax as the sources field:

  1. 'app.py', Pants will convert into the module path.to.app;
  2. 'app.py:func', Pants will convert into path.to.app:func.

You must use the file name shorthand for file arguments to work with this target.

To leave off an entry point, set to '<none>'.

always_write_cache​

bool
default: False

Whether PEX should always write the .deps cache of the .pex file to disk or not. This can use less memory in RAM-constrained environments.

dependencies​

Iterable[str] | None
default: None

Addresses to other targets that this target depends on, e.g. ['helloworld/subdir:lib'].

Alternatively, you may include file names. Pants will find which target owns that file, and create a new target from that which only includes the file in its sources field. For files relative to the current BUILD file, prefix with ./; otherwise, put the full path, e.g. ['./sibling.txt', 'resources/demo.json'].

You may exclude dependencies by prefixing with !, e.g. ['!helloworld/subdir:lib', '!./sibling.txt']. Ignores are intended for false positives with dependency inference; otherwise, simply leave off the dependency from the BUILD file.

description​

str | None
default: None

A human-readable description of the target.

Use ./pants list --documented :: to see all targets with descriptions.

emit_warnings​

bool | None
default: None

Whether or not to emit PEX warnings at runtime.

The default is determined by the option emit_warnings in the [pex-binary-defaults] scope.

execution_mode​

'unzip' | 'venv' | 'zipapp' | None
default: 'zipapp'

The mode the generated PEX file will run in.

The traditional PEX file runs in 'zipapp' mode (See: https://www.python.org/dev/peps/pep-0441/). In general, faster cold start times can be attained using the 'unzip' mode which also has the benefit of allowing standard use of __file__ and filesystem APIs to access code and resources in the PEX.

The fastest execution mode in the steady state is 'venv', which generates a virtual environment from the PEX file on first run, but then achieves near native virtual environment start times. This mode also benefits from a traditional virtual environment sys.path, giving maximum compatibility with stdlib and third party APIs.

ignore_errors​

bool
default: False

Should PEX ignore when it cannot resolve dependencies?

include_tools​

bool
default: False

Whether to include Pex tools in the PEX bootstrap code.

With tools included, the generated PEX file can be executed with PEX_TOOLS=1 <pex file> --help to gain access to all the available tools.

inherit_path​

'fallback' | 'false' | 'prefer' | None
default: None

Whether to inherit the sys.path (aka PYTHONPATH) of the environment that the binary runs in.

Use false to not inherit sys.path; use fallback to inherit sys.path after packaged dependencies; and use prefer to inherit sys.path before packaged dependencies.

interpreter_constraints​

Iterable[str] | None
default: None

The Python interpreters this code is compatible with.

Each element should be written in pip-style format, e.g. 'CPython==2.7.*' or 'CPython>=3.6,<4'. You can leave off CPython as a shorthand, e.g. '>=2.7' will be expanded to 'CPython>=2.7'.

Specify more than one element to OR the constraints, e.g. ['PyPy==3.7.*', 'CPython==3.7.*'] means either PyPy 3.7 or CPython 3.7.

If the field is not set, it will default to the option [python-setup].interpreter_constraints.

See (https://www.pantsbuild.org/v2.5/docs/python-interpreter-compatibility).

output_path​

str | None
default: None

Where the built asset should be located.

If undefined, this will use the path to the BUILD file, followed by the target name. For example, src/python/project:app would be `src.python.project/app.ext.

When running ./pants package, this path will be prefixed by --distdir (e.g. dist/).

Warning: setting this value risks naming collisions with other package targets you may have.

platforms​

Iterable[str] | None
default: None

The platforms the built PEX should be compatible with.

This defaults to the current platform, but can be overridden to different platforms. You can give a list of multiple platforms to create a multiplatform PEX.

To use wheels for specific interpreter/platform tags, you can append them to the platform with hyphens like: PLATFORM-IMPL-PYVER-ABI (e.g. "linux_x86_64-cp-27-cp27mu", "macosx_10.12_x86_64-cp-36-cp36m"):

  • PLATFORM: the host platform, e.g. "linux-x86_64", "macosx-10.12-x86_64".
  • IMPL: the Python implementation abbreviation, e.g. "cp", "pp", "jp".
  • PYVER: a two-digit string representing the Python version, e.g. "27", "36".
  • ABI: the ABI tag, e.g. "cp36m", "cp27mu", "abi3", "none".

shebang​

str | None
default: None

Set the generated PEX to use this shebang, rather than the default of PEX choosing a shebang based on the interpreter constraints.

This influences the behavior of running ./result.pex. You can ignore the shebang by instead running /path/to/python_interpreter ./result.pex.

tags​

Iterable[str] | None
default: None

Arbitrary strings to describe a target.

For example, you may tag some test targets with 'integration_test' so that you could run ./pants --tag='integration_test' test :: to only run on targets with that tag.

zip_safe​

bool
default: True

Whether or not this binary is safe to run in compacted (zip-file) form.

If the PEX is not zip safe, it will be written to disk prior to execution. You may need to mark zip_safe=False if you're having issues loading your code.