A py_binary is an executable Python program consisting
of a collection of .py source files (possibly belonging
to other py_library rules), a *.runfiles
directory tree containing all the code and data needed by the
program at run-time, and a stub script that starts up the program with
the correct initial environment and data.

Examples

If you want to run a py_binary from within another binary or
test (for example, running a python binary to set up some mock resource from
within a java_test) then the correct approach is to make the other binary or
test depend on the py_binary in its data section. The other
binary can then locate the py_binary relative to the source
directory.

Arguments

If main is unspecified, this should be the same as the name
of the source file that is the main entry point of the application,
minus the extension. For example, if your entry point is called
main.py, then your name should be main.

The list of source (.py) files that are processed to create the target.
This includes all your checked-in code and any generated source files. Library targets
belong in deps instead, while other binary files needed at runtime belong in
data.

A deprecated alias for python_version; use that instead. This attribute is
disabled under --incompatible_remove_old_python_version_api. For migration
purposes, if python_version is given then the value of
default_python_version is ignored.

imports

List of strings; optional

List of import directories to be added to the PYTHONPATH.

Subject to "Make variable" substitution. These import
directories will be added for this rule and all rules that depend on it (note: not the
rules this rule depends on. Each directory will be added to PYTHONPATH by
py_binary rules that depend on this rule.

Absolute paths (paths that start with /) and paths that references a path
above the execution root are not allowed and will result in an error.

legacy_create_init

Boolean; optional; default is True

Whether to implicitly create empty __init__.py files in the runfiles tree.
These are created in every directory containing Python source code or
shared libraries, and every parent directory of those directories, excluding the repo root
directory. The default is true for backward compatibility. If false, the user is
responsible for creating (possibly empty) __init__.py files and adding them to the
srcs of Python targets as required.

The name of the source file that is the main entry point of the application.
This file must also be listed in srcs. If left unspecified,
name is used instead (see above). If name does not
match any filename in srcs, main must be specified.

Whether to build this target (and its transitive deps) for Python 2 or Python
3. Valid values are "PY2" (the default) and "PY3".

Under the old semantics
(--incompatible_allow_python_version_transitions=false), the Python version
generally cannot be changed once set. This means that the --python_version
flag overrides this attribute, and other Python binaries in the data deps of
this target are forced to use the same version as this target.

Under the new semantics
(--incompatible_allow_python_version_transitions=true), the Python version
is always set (possibly by default) to whatever version is specified by this attribute,
regardless of the version specified on the command line or by other targets that depend on
this one.

If you want to select() on the current Python version, you can inspect the
value of @bazel_tools//tools/python:python_version. See
here
for more information.

Bug warning: This attribute sets the version for which Bazel builds your target,
but due to #4815, the
resulting stub script may still invoke the wrong interpreter version at runtime. See
this
workaround, which involves defining a py_runtime target that points to
either Python version as needed, and activating this py_runtime by setting
--python_top.

srcs_version

String; optional; default is "PY2AND3"

This attribute declares the target's srcs to be compatible with either Python
2, Python 3, or both. To actually set the Python runtime version, use the
python_version attribute of an
executable Python rule (py_binary or py_test).

Allowed values are: "PY2AND3", "PY2", and "PY3".
The values "PY2ONLY" and "PY3ONLY" are also allowed for historic
reasons, but they are essentially the same as "PY2" and "PY3"
and should be avoided.

Under the old semantics
(--incompatible_allow_python_version_transitions=false), it is an error to
build any Python target for a version disallowed by its srcs_version
attribute. Under the new semantics
(--incompatible_allow_python_version_transitions=true), this check is
deferred to the executable rule: You can build a srcs_version = "PY3"py_library target for Python 2, but you cannot actually depend on it via
deps from a Python 3 py_binary.

To get diagnostic information about which dependencies introduce version requirements,
you can run the find_requirements aspect on your target:

This will build a file with the suffix -pyversioninfo.txt giving information
about why your target requires one Python version or another. Note that it works even if
the given target failed to build due to a version conflict.

The list of source (.py) files that are processed to create the target.
This includes all your checked-in code and any generated source files.

imports

List of strings; optional

List of import directories to be added to the PYTHONPATH.

Subject to "Make variable" substitution. These import
directories will be added for this rule and all rules that depend on it (note: not the
rules this rule depends on. Each directory will be added to PYTHONPATH by
py_binary rules that depend on this rule.

Absolute paths (paths that start with /) and paths that references a path
above the execution root are not allowed and will result in an error.

srcs_version

String; optional; default is "PY2AND3"

This attribute declares the target's srcs to be compatible with either Python
2, Python 3, or both. To actually set the Python runtime version, use the
python_version attribute of an
executable Python rule (py_binary or py_test).

Allowed values are: "PY2AND3", "PY2", and "PY3".
The values "PY2ONLY" and "PY3ONLY" are also allowed for historic
reasons, but they are essentially the same as "PY2" and "PY3"
and should be avoided.

Under the old semantics
(--incompatible_allow_python_version_transitions=false), it is an error to
build any Python target for a version disallowed by its srcs_version
attribute. Under the new semantics
(--incompatible_allow_python_version_transitions=true), this check is
deferred to the executable rule: You can build a srcs_version = "PY3"py_library target for Python 2, but you cannot actually depend on it via
deps from a Python 3 py_binary.

To get diagnostic information about which dependencies introduce version requirements,
you can run the find_requirements aspect on your target:

This will build a file with the suffix -pyversioninfo.txt giving information
about why your target requires one Python version or another. Note that it works even if
the given target failed to build due to a version conflict.

The list of source (.py) files that are processed to create the target.
This includes all your checked-in code and any generated source files. Library targets
belong in deps instead, while other binary files needed at runtime belong in
data.

A deprecated alias for python_version; use that instead. This attribute is
disabled under --incompatible_remove_old_python_version_api. For migration
purposes, if python_version is given then the value of
default_python_version is ignored.

imports

List of strings; optional

List of import directories to be added to the PYTHONPATH.

Subject to "Make variable" substitution. These import
directories will be added for this rule and all rules that depend on it (note: not the
rules this rule depends on. Each directory will be added to PYTHONPATH by
py_binary rules that depend on this rule.

Absolute paths (paths that start with /) and paths that references a path
above the execution root are not allowed and will result in an error.

legacy_create_init

Boolean; optional; default is True

Whether to implicitly create empty __init__.py files in the runfiles tree.
These are created in every directory containing Python source code or
shared libraries, and every parent directory of those directories, excluding the repo root
directory. The default is true for backward compatibility. If false, the user is
responsible for creating (possibly empty) __init__.py files and adding them to the
srcs of Python targets as required.

The name of the source file that is the main entry point of the application.
This file must also be listed in srcs. If left unspecified,
name is used instead (see above). If name does not
match any filename in srcs, main must be specified.

Whether to build this target (and its transitive deps) for Python 2 or Python
3. Valid values are "PY2" (the default) and "PY3".

Under the old semantics
(--incompatible_allow_python_version_transitions=false), the Python version
generally cannot be changed once set. This means that the --python_version
flag overrides this attribute, and other Python binaries in the data deps of
this target are forced to use the same version as this target.

Under the new semantics
(--incompatible_allow_python_version_transitions=true), the Python version
is always set (possibly by default) to whatever version is specified by this attribute,
regardless of the version specified on the command line or by other targets that depend on
this one.

If you want to select() on the current Python version, you can inspect the
value of @bazel_tools//tools/python:python_version. See
here
for more information.

Bug warning: This attribute sets the version for which Bazel builds your target,
but due to #4815, the
resulting stub script may still invoke the wrong interpreter version at runtime. See
this
workaround, which involves defining a py_runtime target that points to
either Python version as needed, and activating this py_runtime by setting
--python_top.

srcs_version

String; optional; default is "PY2AND3"

This attribute declares the target's srcs to be compatible with either Python
2, Python 3, or both. To actually set the Python runtime version, use the
python_version attribute of an
executable Python rule (py_binary or py_test).

Allowed values are: "PY2AND3", "PY2", and "PY3".
The values "PY2ONLY" and "PY3ONLY" are also allowed for historic
reasons, but they are essentially the same as "PY2" and "PY3"
and should be avoided.

Under the old semantics
(--incompatible_allow_python_version_transitions=false), it is an error to
build any Python target for a version disallowed by its srcs_version
attribute. Under the new semantics
(--incompatible_allow_python_version_transitions=true), this check is
deferred to the executable rule: You can build a srcs_version = "PY3"py_library target for Python 2, but you cannot actually depend on it via
deps from a Python 3 py_binary.

To get diagnostic information about which dependencies introduce version requirements,
you can run the find_requirements aspect on your target:

This will build a file with the suffix -pyversioninfo.txt giving information
about why your target requires one Python version or another. Note that it works even if
the given target failed to build due to a version conflict.

stamp

Integer; optional; default is 0

See the section on py_binary() arguments, except
that the stamp argument is set to 0 by default for tests.