feat: add py_zipapp_binary and test rules for zipapp support #3539

rickeylev · 2026-01-25T00:41:33Z

This adds Python zipapp support as a separate rule that works with a py_binary.

This will eventually replace the zipapp logic that is directly part of py_binary.

The high level behavior should be the same, but there's a few differences and improvements:

Changes:

Output name is {name}.pyz
Whether the output is executable is controlled by attribute, not flag.

Improvements:

Compression level can be explicitly controlled.
Re-unzipping optimization: only unzip if the zip's hash changed
Zip output is more deterministic (input order doesn't affect output)
runfiles.symlinks, runfiles.root_symlinks, and raw symlinks are supported
Zipping venv-based binary is supported
Lower analysis-phase cost
Self-execution doesn't require python itself

For now, this lacks Windows support for lack of time (it requires plumbing in the
"windows exe maker" stuff or equivalent for self-executable zip support).

Along the way:

Add PyExecToolsInfo.exec_runtime: an easier way to get the RBE-compatible runtime
Add PyExecutableInfo fields to aid packaging a binary.
Set --verbose_failures in CI config to give more info when actions fail.
Make --visible_for_testing a command line flag. This makes it a bit easier to
debug toolchain issues by showing the source of the toolchain.
Add actions_run helper: this makes it easier to use py scripts as build actions.

Work towards #3324 #2586

gemini-code-assist · 2026-01-25T00:42:05Z

Summary of Changes

Hello @rickeylev, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive overhaul of Python zip application (zipapp) support within the Bazel rules. By extracting zipapp creation into new, dedicated py_zipapp_binary and py_zipapp_test rules, the change aims to provide a more robust, feature-rich, and performant mechanism for packaging Python applications. It enhances control over the build process, improves determinism, and lays the groundwork for future advancements in Python binary distribution.

Highlights

New Zipapp Rules Introduced: Dedicated py_zipapp_binary and py_zipapp_test rules have been added to replace the existing zipapp logic within py_binary and py_test. These new rules offer enhanced functionality and improved build performance.
Improved Zipapp Features: The new zipapp rules provide explicit control over compression levels, optimize re-unzipping by checking the zip's hash, ensure more deterministic zip output, and support various symlink types (runfiles.symlinks, runfiles.root_symlinks, and raw symlinks). They also support zipping venv-based binaries.
Output and Executability: Generated zipapps now have a .pyz extension, and their executability is controlled via a dedicated attribute rather than a flag, offering more granular control.
Refactored Internal Logic: Significant internal refactoring has occurred, including the introduction of maybe_create_repo_mapping and actions_run functions in common.bzl, and a more detailed PyExecutableInfo provider to support the new zipapp structure and its various components like app_runfiles and stage2_bootstrap.
New Tools and Templates: New Python scripts (zipper.py, exe_zip_maker.py) and shell/Python templates (zip_shell_template.sh, zipapp_stage2_bootstrap_template.py) have been added to facilitate the creation and execution of these advanced zipapps.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a significant new feature: dedicated rules for creating Python zipapps (py_zipapp_binary and py_zipapp_test). This is a substantial refactoring that moves zipapp creation logic out of the generic py_binary rule, improving modularity and adding features like explicit compression control and enhanced determinism. The changes are extensive, touching many parts of the Python rules, including common utilities, executable creation, and providers. The new tooling for zipping and creating executables is well-designed and thoroughly tested.

Overall, the implementation is of high quality. However, I've identified a couple of critical issues in the new macros that would lead to build failures due to missing imports. I've also found a logic bug in a shell script template that affects a debugging feature. I've provided suggestions to fix these issues. The rest of the changes, including the refactoring of runfiles handling and the new actions_run helper, are excellent improvements.

python/zipapp/py_zipapp_binary.bzl

python/zipapp/py_zipapp_test.bzl

python/private/zipapp/zip_shell_template.sh

…into refactor.pyzipapp

rickeylev · 2026-01-31T17:46:55Z

@gemini-code-assist review

gemini-code-assist

Code Review

This pull request introduces py_zipapp_binary and py_zipapp_test rules, a significant enhancement for Python zipapp support that will eventually replace the existing logic within py_binary. The changes are extensive, refactoring core py_executable logic to expose more details for packaging, adding new tools for zip creation, and including a comprehensive set of tests. The implementation is well-structured, with new logic cleanly organized into a new zipapp package. I've identified a couple of potential issues with argument handling that could cause build failures in certain edge cases, but overall, this is an excellent and valuable addition to rules_python.

python/private/zipapp/py_zipapp_rule.bzl

python/private/common.bzl

rickeylev · 2026-01-31T17:57:07Z

OK, ready for review. PTAL

…into refactor.pyzipapp

aignas

In general LGTM. Thank you for easy to read code!

aignas · 2026-02-01T06:03:41Z

python/private/zipapp/py_zipapp_rule.bzl

+    return "rf-file|" + _is_symlink(file) + "|" + file.short_path + "|" + file.path
+
+def _map_zip_symlinks(entry):
+    return "rf-symlink|" + _is_symlink(entry.target_file) + "|" + entry.path + "|" + entry.target_file.path


nit: I remember that "%s" % "foo" being faster than "{}".format. Is + even better to use than "%s" or are they equivalent?

aignas · 2026-02-01T06:05:23Z

python/private/zipapp/py_zipapp_rule.bzl

+def _create_self_executable_zip(ctx, preamble, zip_file):
+    pyz = ctx.actions.declare_file(ctx.label.name + ".pyz")
+    args = ctx.actions.args()
+    args.add(preamble)


nit: why not use add_all?

aignas · 2026-02-01T06:06:35Z

python/private/zipapp/py_zipapp_rule.bzl

+
+py_zipapp_binary = rule(
+    doc = """
+Packages a `py_binary` as a Python zipapp.


Is the zipapp the same as https://docs.python.org/3/library/zipapp.html?

aignas · 2026-02-01T07:01:37Z

python/private/py_exec_tools_info.bzl

+exec_runtime = (
+    ctx.toolchains["@rules_python//python:exec_tools_toolchain_type"].
+        exec_tools.exec_interpreter[platform_common.ToolchainInfo].py3_runtime
+    )
+```


This is a great addition!

aignas · 2026-02-01T07:02:53Z

python/private/py_exec_tools_toolchain.bzl

+
+        # NOTE: Using ctx.actions.symlink() here doesn't always work with RBE
+        # because it's not guaranteed that it will materialize as a symlink, but
+        # we rely on it being a symlink so that Python can find its actual


what does this mean to me as a maintainer. Do some RBE implementation not work with our code? Does it not work sometimes? Do we have the RBE support for this disabled because of this?

aignas · 2026-02-01T07:09:00Z

tools/zipapp/exe_zip_maker.py

@@ -0,0 +1,40 @@
+import hashlib


Is this private to the zipapp? I would personally have it in python/private/zipapp/exe_zip_maker.py until somebody comes along and asks for this to be exposed.

aignas · 2026-02-01T07:09:22Z

tools/zipapp/zipper.py

@@ -0,0 +1,230 @@
+import argparse


aignas · 2026-02-01T07:10:13Z

CHANGELOG.md

  that are associated with the target's `srcs` are present.
  ([#3354](https://github.com/bazel-contrib/rules_python/issues/3354)).
+* (zipapp) {obj}`py_zipapp_binary` and {obj}`py_zipapp_test` rules added. These
+  will replace `--build_python_zip` and the zip output group of


when do you want to replace these? Next major version? Should we add some deprecation messages?

aignas · 2026-02-01T07:11:22Z

tests/py_zipapp/BUILD.bazel

+py_zipapp_binary(
+    name = "system_python_zipapp",
+    binary = ":system_python_bin",
+    target_compatible_with = NOT_WINDOWS,


What about windows and zipapps? If I understand correctly, Windows most of the time is building zips under the hood?

It would be good to have a comment somewhere about plans/strategy of this.

rickeylev requested a review from aignas as a code owner January 25, 2026 00:41

gemini-code-assist bot reviewed Jan 25, 2026

View reviewed changes

python/zipapp/py_zipapp_binary.bzl Show resolved Hide resolved

python/zipapp/py_zipapp_test.bzl Show resolved Hide resolved

python/private/zipapp/zip_shell_template.sh Outdated Show resolved Hide resolved

rickeylev force-pushed the refactor.pyzipapp branch from 74ff6b0 to 7ac5c39 Compare January 25, 2026 00:48

basic impl

149a840

rickeylev force-pushed the refactor.pyzipapp branch from 7ac5c39 to 149a840 Compare January 25, 2026 02:12

rickeylev added 10 commits January 24, 2026 19:37

Merge branch 'main' of https://github.com/bazel-contrib/rules_python …

a95377e

…into refactor.pyzipapp

disable test pre-bazel 8

1f22bdc

Merge branch 'main' of https://github.com/bazel-contrib/rules_python …

9328fbe

…into refactor.pyzipapp

add bazel 7 support

adb589f

make test support workspace mode

8ced1db

cleanup

5dbfab4

basic impl of config_settings attr

89b438a

add missing bzl deps

5ae496e

format code

3518a8b

disable buildifier warning

b23f452

rickeylev mentioned this pull request Jan 26, 2026

pkg_zip creates the zip file with broken link inside venv #3545

Open

rickeylev added 13 commits January 26, 2026 17:34

fix case when venv is none

6528660

add system_python test case

4046f98

handle venv none in create_executable

a41b4fc

make zipapp transition set build zip to false

f6a3324

try setting command_line_option:build_python_zip=false

e3b223d

add cli:build_python_zip to transition outputs

895d21b

use correct type for cli:build_python_zip

678ea62

disable windows for zipapp tests

5cdfd85

trying to debug windows

cf2daa5

run fewer presubmits

ce0bb07

fix missing symbol loads

f1dd5fc

add missing bzl dep, skip BCR test

22387dc

undo anti-zipper debug logic

3274d73

rickeylev added 18 commits January 27, 2026 20:08

improving test error reporting

9946c2e

write bytes, not text, to avoid windows-specific line endings

a7cca04

re enable all presubmits

860f561

Merge branch 'main' of https://github.com/bazel-contrib/rules_python …

0df803f

…into refactor.pyzipapp

debug logic for RBE

d9a0f5f

more rbe debugging

a8d9bd0

make visible_for_testing a flag, more debug print

0209bb8

try declare_symlink instead of declare_file

716c45c

undo declare_symlink; doesnt work with symlink(target_file)

06af34a

maybe found RBE solution?

702794f

undo more presubmit debug

f62f485

switch to bool_flag, remove extra escape

0e244bf

remove extraneous trap in shell bootstrap

d71691a

remove defunct maybe_builtin_build_python_zip

ad51589

add exec_runtime field, cleanup debug code

1d2e8c9

add exec_runtime to changelog

d4a6ca2

fix null check in exec toolchain rule

01d52a6

cleanup: doc new fields, remove debug from presubmit, changelog fixes

eba18ed

gemini-code-assist bot reviewed Jan 31, 2026

View reviewed changes

python/private/zipapp/py_zipapp_rule.bzl Show resolved Hide resolved

python/private/common.bzl Outdated Show resolved Hide resolved

handle arguments=None in actions_run

bd28f94

rickeylev mentioned this pull request Jan 31, 2026

Canonical way to isolate binary info from PyExecutableInfo #3324

Open

Merge branch 'main' of https://github.com/bazel-contrib/rules_python …

badc4ef

…into refactor.pyzipapp

aignas approved these changes Feb 1, 2026

View reviewed changes

Uh oh!

feat: add py_zipapp_binary and test rules for zipapp support #3539

Are you sure you want to change the base?

feat: add py_zipapp_binary and test rules for zipapp support #3539

Uh oh!

Conversation

rickeylev commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Jan 25, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rickeylev commented Jan 31, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

rickeylev commented Jan 31, 2026

Uh oh!

aignas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rickeylev commented Jan 25, 2026 •

edited

Loading