Skip to main content
Version: 2.14 (deprecated)

pyoxidizer_binary

A single-file Python executable with a Python interpreter embedded, built via PyOxidizer.

To use this target, first create a python_distribution target with the code you want included in your binary, per https://www.pantsbuild.org/v2.14/docs/python-distributions. Then add this python_distribution target to the dependencies field. See the help for dependencies for more information.

You may optionally want to set the entry_point field. For advanced use cases, you can use a custom PyOxidizer config file, rather than what Pants generates, by setting the template field. You may also want to set [pyoxidizer].args to a value like ['--release'].

Backend: pants.backend.experimental.python.packaging.pyoxidizer

dependencies​

Iterable[str]
required

The addresses of python_distribution target(s) to include in the binary, e.g. ['src/python/project:dist'].

The distribution(s) must generate at least one wheel file. For example, if using generate_setup=True, then make sure wheel=True. See https://www.pantsbuild.org/v2.14/docs/python-distributions.

Usually, you only need to specify a single python_distribution. However, if that distribution depends on another first-party distribution in your repository, you must specify that dependency too, otherwise PyOxidizer would try installing the distribution from PyPI. Note that a python_distribution target might depend on another python_distribution target even if it is not included in its own dependencies field, as explained at https://www.pantsbuild.org/v2.14/docs/python-distributions; if code from one distribution imports code from another distribution, then there is a dependency and you must include both python_distribution targets in the dependencies field of this pyoxidizer_binary target.

Target types other than python_distribution will be ignored.

description​

str | None
default: None

A human-readable description of the target.

Use /home/josh/work/scie-pants/dist/pants list --documented :: to see all targets with descriptions.

entry_point​

str | None
default: None

Set the entry point, i.e. what gets run when executing ./my_app, to a module. This represents the content of PyOxidizer's python_config.run_module and leaving this field empty will create a REPL binary.

It is specified with the full module declared: 'path.to.module'.

This field is passed into the PyOxidizer config as-is, and does not undergo validation checking.

filesystem_resources​

Iterable[str] | None
default: None

Adds support for listing dependencies that MUST be installed to the filesystem (e.g. Numpy). See https://pyoxidizer.readthedocs.io/en/stable/pyoxidizer_packaging_additional_files.html#installing-unclassified-files-on-the-filesystem

output_path​

str | None
default: None

Where the built directory tree should be located.

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

Regardless of whether you use the default or set this field, the path will end with PyOxidizer's file format of <platform>/{debug,release}/install/<binary_name>, where platform is a Rust platform triplet like aarch-64-apple-darwin and binary_name is the name of the pyoxidizer_target. So, using the default for this field, the target src/python/project:bin might have a final path like src.python.project/bin/aarch-64-apple-darwin/release/bin.

When running /home/josh/work/scie-pants/dist/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.

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 /home/josh/work/scie-pants/dist/pants --tag='integration_test' test :: to only run on targets with that tag.

template​

str | None
default: None

If set, will use your custom configuration rather than using Pants's default template.

The path is relative to the BUILD file's directory, and it must end in .blzt.

All parameters must be prefixed by $ or surrounded with ${ }.

Available template parameters:

  • RUN_MODULE - The re-formatted entry_point passed to this target (or None).
  • NAME - This target's name.
  • WHEELS - All python distributions passed to this target (or []).
  • UNCLASSIFIED_RESOURCE_INSTALLATION - This will populate a snippet of code to correctly inject the targets filesystem_resources.