aspect_rules_py

[!NOTE] This repository uses the Aspect CLI for CI and local development. See the docs and install instructions to get started.

[!WARNING] This is the 2.x ALPHA branch. APIs and behavior may change without notice. For stable documentation, see the 1.x branch.

aspect_rules_py is a high-performance alternative to rules_python, the reference Python ruleset for Bazel.

It provides drop-in replacements for py_binary, py_library, and py_test that prioritize:

• Blazing-fast dependency resolution via native uv integration
• Strict hermeticity with isolated Python execution and Bash-based launchers
• Idiomatic Python layouts using standard site-packages symlink trees
• Seamless IDE compatibility via virtualenv-native structures
• Production-ready containers with optimized OCI image layers

aspect_rules_py optimizes for modern Python development workflows, large-scale monorepos, and Remote Build Execution ( RBE) environments.

Advantages Over rules_python

Feature	rules_python	rules_py
Dependency resolution	pip.parse (repo rules, loading phase)	Build-action wheel installs (whl_install)
uv integration	uv pip compile → requirements.txt → pip.parse	Native uv.lock consumption
Cross-platform lockfile	requirements.txt (uv.lock via uv pip compile)	Native single uv.lock consumption
sdist / PEP 517 builds	Not supported (#2410, open since Nov 2024)	Build actions (pep517_whl, pep517_native_whl)
Interpreter provisioning	Download via rules_python extension	Own python-build-standalone extension — no rules_python required
Site-packages layout	Standard site-packages layout (flag-enabled)	Standard site-packages symlink tree
Cross-compilation	Limited	Native platform transitions (e.g. arm64 image on amd64 host)
Virtual dependencies	No	virtual_deps — swap implementations at binary level
PEP 735 dependency groups	No	--@pypi//dep_group=prod flag

[!NOTE] rules_python's uv support: rules_python's uv integration runs uv pip compile as a build action to generate a requirements.txt—it is a faster pip-compile replacement. The result still feeds into pip.parse() → whl_library repository rules at loading phase. There is no uv.lock consumption; the rules_python maintainer has suggested this work belongs in a dedicated project.

Native uv.lock Dependency Resolution

Instead of relying on legacy pip machinery, we provide native integration with uv, a Rust-native Python package resolver.

• Build-action installs: Wheel extraction runs as Bazel execution-phase actions—not repo rules—so they are sandboxed and compatible with RBE. Crucially, wheels are no longer resolved against the host machine architecture: a single build can fetch and extract wheels for any exec or target platform, enabling true cross-platform builds (e.g. building Linux aarch64 wheels on a macOS x86_64 host)
• Native uv.lock parsing: Consumes uv.lock directly; no requirements.txt generation step
• Universal lockfiles: A single uv.lock works across all platforms
• sdist / PEP 517 builds: Build source distributions as Bazel actions (rules_python has no equivalent; #2410 open since November 2024)
• PEP 735 dependency groups: Define prod, dev, test dependency groups and switch between them with a flag
• Editable requirements: Override locked packages with local py_library targets via uv.override_package()
• Lazy downloads: Wheel installation happens during the build phase, not repository loading—fully compatible with private mirrors and RBE

Own Python Interpreter Provisioning

aspect_rules_py ships its own python-build-standalone interpreter extension—rules_python is not required as a toolchain provider.

[!NOTE] The //py and //uv extension paths provide stable APIs for interpreter provisioning and dependency resolution. They graduated from //py/unstable and //uv/unstable in rules_py v2.0.0.

interpreters = use_extension("@aspect_rules_py//py:extensions.bzl", "python_interpreters")
interpreters.toolchain(python_version = "3.12")
use_repo(interpreters, "python_interpreters")
register_toolchains("@python_interpreters//:all")

# .bazelrc
common --@aspect_rules_py//py:python_version=3.12

This enables cross-compilation from any host to any target without host-installed Python, and is the foundation for correct toolchain selection in RBE environments.

Idiomatic site-packages Layout

We do not manipulate sys.path or $PYTHONPATH. Instead, we generate a standard site-packages directory structure using symlink trees:

• Prevents module name collisions (e.g., standard library collections vs. a transitive dependency named collections)
• Matches standard Python expectations—tools just work
• Native IDE compatibility: VSCode, PyCharm, and language servers resolve jump-to-definition correctly into the Bazel sandbox

Strict Sandbox Isolation

• Isolated mode: Python executes with -I flag, preventing implicit loading of user site-packages or host environment variables
• Hermetic launchers: Our launcher uses the Bazel Bash toolchain, not the host Python, this ensures 100% hermetic execution across local machines and RBE nodes
• No host Python leakage: Breaks the implicit dependency on system Python during the boot sequence

Cross-Platform & Cross-Build Native

• Effortless cross-compilation: Build Linux container images from macOS (or vice versa) using standard Bazel platform transitions
• Multi-architecture OCI images: Native support for building amd64 and arm64 container images
• Platform-agnostic queries: All hub labels are always available—no more "target incompatible" errors when querying on a different OS

Virtual Dependencies for Monorepos

virtual_deps allow external Python dependencies to be specified by package name rather than by label:

• Individual projects within a monorepo can upgrade dependencies independently
• Test against multiple versions of the same dependency
• Swap implementations at the binary level (e.g., use cowsnake instead of cowsay)

Production Container Support

Built-in rules for creating optimized container images:

• py_image_layer: Creates layered tar files compatible with rules_oci
• Cross-platform builds with automatic platform transitions
• Optimized layer caching—dependencies and application code are separated

Native Pytest Integration

• First-class pytest support with py_pytest_test
• Automatic test discovery with proper import handling
• Compatible with pytest-mock, pytest-xdist, and other plugins

Installation and Configuration

bazel_dep(name = "aspect_rules_py", version = "1.11.2")

Requirements

The minimum supported Python version is 3.10. The launcher, test runners, and build tools that run under your configured interpreter use 3.10 syntax, and CI only exercises 3.10 and newer. Older interpreters can still be fetched via interpreters.configure(), but py_binary and py_test targets will fail at startup on them.

Some uv features need newer versions:

Feature	Python
Free-threaded interpreters (freethreaded = True), first shipped in CPython 3.13	3.13+
pyproject.toml parsing in sdist native-dependency detection (needs stdlib tomllib)	3.11+

Quick Start

Load rules from aspect_rules_py in your BUILD files:

load("@aspect_rules_py//py:defs.bzl", "py_binary", "py_library", "py_test")

py_library(
    name = "lib",
    srcs = ["lib.py"],
    deps = ["@pypi//requests"],
)

py_binary(
    name = "app",
    srcs = ["main.py"],
    main = "main.py",
    deps = [":lib"],
)

py_test(
    name = "test",
    srcs = ["test.py"],
    deps = [":lib"],
)

Dependency Resolution with uv

aspect_rules_py//uv is our alternative to rules_python's pip.parse:

uv = use_extension("@aspect_rules_py//uv:extensions.bzl", "uv")

# 1. Declare a hub (a shared dependency namespace)
uv.declare_hub(
    hub_name = "pypi",
)

# 2. Register projects (lockfiles) into the hub
uv.project(
    hub_name = "pypi",
    lock = "//:uv.lock",
    pyproject = "//:pyproject.toml",
    # Build tools injected for sdist packages that need them (e.g. maturin, setuptools)
    default_build_dependencies = ["build", "setuptools"],
)

# 3a. (Optional) Replace a package with a local Bazel target
uv.override_package(
    name = "some_package",
    lock = "//:uv.lock",
    target = "//third_party/some_package",
)

# 3b. (Optional) Patch an installed wheel's file tree after unpacking
uv.override_package(
    name = "some_other_package",
    lock = "//:uv.lock",
    post_install_patches = ["//third_party/patches:fix_some_other_package.patch"],
)

# 3c. (Optional) Remove bundled tests or other unused wheel content
uv.override_package(
    name = "another_package",
    lock = "//:uv.lock",
    exclude_glob = ["another_package/**/tests/**"],
)

# 3d. (Optional) Restrict a package and its dependents to test targets
uv.override_package(
    name = "pytest-postgresql",
    lock = "//:uv.lock",
    testonly = True,
)

use_repo(uv, "pypi")

Requirements are declared in standard pyproject.toml:

[project]
name = "myapp"
version = "1.0.0"
requires-python = ">= 3.11"
dependencies = [
    "requests>=2.28",
    "pydantic>=2.0",
]

[dependency-groups]
dev = ["pytest", "black", "mypy"]

Generate the lockfile with uv:

uv lock

Switch between dependency groups:

# Default: use all dependencies
bazel run //:app

# Use only production dependencies
bazel run //:app --@pypi//dep_group=prod

Virtual Dependencies

Declare virtual dependencies in libraries:

py_library(
    name = "greet_lib",
    srcs = ["greet.py"],
    virtual_deps = ["cowsay"],  # Not a label—just a package name
)

Resolve them in binaries:

py_binary(
    name = "app",
    srcs = ["main.py"],
    deps = [":greet_lib"],
    resolutions = {
        "cowsay": "@pypi//cowsay",
    },
)

# Or use a different implementation!
py_binary(
    name = "app_snake",
    srcs = ["main.py"],
    deps = [":greet_lib"],
    resolutions = {
        "cowsay": "//cowsnake",  # Swapped implementation
    },
)

Container Images

Build optimized OCI images with layer caching:

load("@aspect_rules_py//py:defs.bzl", "py_binary", "py_image_layer")
load("@rules_oci//oci:defs.bzl", "oci_image", "oci_load")

py_binary(
    name = "app_bin",
    srcs = ["main.py"],
    deps = ["//:lib"],
)

py_image_layer(
    name = "app_layers",
    binary = ":app_bin",
)

oci_image(
    name = "image",
    base = "@ubuntu",
    tars = [":app_layers"],
    entrypoint = ["/app/app_bin"],
)

oci_load(
    name = "image_load",
    image = ":image",
    repo_tags = ["myapp:latest"],
)

Cross-compile for Linux from macOS:

bazel build //:image --platforms=//platforms:linux_amd64

Layer compression

Layers are written by bsdtar, so any libarchive write filter can compress them: none, gzip (the default, level 6), bzip2, xz, lzma, lzop, lz4, lrzip, zstd, and compress. The file extension follows the filter, which is what image tooling reads the layer's media type from.

The OCI image spec only defines tar, +gzip and +zstd layers, so those are the three you can put in an image. rules_oci identifies a layer's compression by sniffing its magic; a codec it cannot sniff is labelled an uncompressed tar and keeps the compressed digest as its diffid, which builds successfully and produces an invalid image. py_image_layer and py_layer_tier therefore reject the other filters unless you set allow_non_oci_layers = True, which declares that the tars are going somewhere other than an OCI image.

py_layer_tier sets compression for the layers it names — pip packages, the interpreter, and first-party groups:

load("@aspect_rules_py//py:defs.bzl", "py_layer_tier")

py_layer_tier(
    name = "tier",
    groups = {
        "@pip//torch": "heavy",
        "//src/common": "common",
    },
    interpreter_group = "interpreter",
    compression = {
        "heavy": ["zstd", "19"],   # [algorithm, level]
        "common": ["gzip"],        # level omitted: libarchive's default
        "interpreter": ["none"],   # an uncompressed layer
    },
)

py_image_layer sets compression for the layers it creates itself — the groups tars, the squashed pip layer ("packages"), and the source layer ("default") — and takes precedence over the tier for a group both name:

py_image_layer(
    name = "app_layers",
    binary = ":app_bin",
    layer_tier = ":tier",
    group_compression = {"default": ["zstd", "3"]},
)

For a different implementation of a codec — pigz, a tuned zstd — declare a py_layer_compressor. bsdtar pipes the archive through the program, so anything that reads stdin and writes compressed bytes to stdout works. The extension is how you declare what it emits, and it decides whether the result is OCI-valid:

load("@aspect_rules_py//py:defs.bzl", "py_layer_compressor")

py_layer_compressor(
    name = "pigz",
    tool = "//tools:pigz",
    args = ["-11"],
    extension = ".tar.gz",  # gzip bytes, so a valid OCI layer
)

py_layer_tier(
    name = "tier",
    groups = {"@pip//torch": "heavy"},
    compressors = {":pigz": "heavy"},
)

A compressor declaring anything other than .tar, .tar.gz or .tar.zst is treated as non-OCI and needs allow_non_oci_layers = True — the program's bytes are opaque, so the extension is the only claim available about what an image consumer would find.

py_image_layer accepts the same mapping as group_compressors for its own tars. Note that lzop and lrzip are the two filters libarchive implements by shelling out to a same-named binary, which a sandboxed action is not guaranteed to have — prefer a py_layer_compressor there.

IDE Integration

aspect_rules_py generates standard virtualenv structures that IDEs understand. In v2.0 the venv targets that the v1.x docs auto-emitted alongside every py_binary are opt-in — declare them on the targets you actually want your IDE to follow.

The recommended one-liner:

load("@aspect_rules_py//py:defs.bzl", "py_binary")

py_binary(
    name = "my_app",
    srcs = ["main.py"],
    main = "main.py",
    expose_venv_link = True,   # publishes :my_app.venv + :my_app.venv_link
)

expose_venv_link = True emits two sibling targets:

• bazel run //:my_app.venv — drops you into the hermetic interpreter REPL with the venv activated. Useful for ad-hoc Python sessions matching your binary's deps.
• bazel run //:my_app.venv_link — materialises a workspace-local symlink pointing at the target's complete runfiles tree and prints the venv's nested path below that link. Point your IDE at the printed venv path.

Then point your IDE to the virtualenv path printed by the command:

• VSCode: Set python.defaultInterpreterPath to the printed path
• PyCharm: Add the printed venv path as a Python interpreter
• Neovim/LSP: Configure python-lsp-server or pyright to use the virtualenv

Underlying mechanism

expose_venv_link = True is sugar for the explicit two-target shape:

py_binary(
    name = "my_app",
    srcs = ["main.py"],
    main = "main.py",
    expose_venv = True,
)

py_venv_link(
    name = "my_app.venv_link",
    venv = ":my_app.venv",
)

Reach for the explicit form when you want to customise py_venv_link's link_name, point it at a standalone py_venv (declared independently of any binary, useful for an IDE-only environment), or selectively skip the link target on a subset of binaries.

Migrating from v1.x? py_binary no longer auto-emits a .venv sibling. Add expose_venv_link = True for the equivalent IDE-symlink behavior, or use the explicit two-target form when you want fine-grained control. The workspace link now points to the complete runfiles tree, so update IDE, shell, direnv, and automation paths such as .venv/bin to use the nested virtualenv path printed by bazel run :<name>.venv_link.

Debugger Support (VSCode/PyCharm)

Attach DAP-compatible debuggers (VSCode, PyCharm, Neovim, etc.) using debugpy. This requires a wrapper entrypoint that starts a debugpy listener before running your application — simply adding debugpy to deps is not enough.

See the complete debugger example for a working setup, including a py_debuggable_binary macro that handles the wrapper generation automatically.

Quick overview:

cd examples/debugger

# Start with debugpy listener, wait for IDE to attach:
DEBUGPY_WAIT=1 bazel run //:app

# Release mode — no debugpy, runs directly:
bazel run //:app --config=release

VSCode launch.json:

{
  "name": "Attach to Bazel py_binary",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "127.0.0.1",
    "port": 5678
  }
}

Gazelle Integration

Generate BUILD files automatically with the Gazelle extension:

# MODULE.bazel
bazel_dep(name = "gazelle", version = "0.42.0")
bazel_dep(name = "aspect_rules_py", version = "1.11.2")

# In your BUILD file
# gazelle:map_kind py_library py_library @aspect_rules_py//py:defs.bzl
# gazelle:map_kind py_binary py_binary @aspect_rules_py//py:defs.bzl
# gazelle:map_kind py_test py_test @aspect_rules_py//py:defs.bzl

# Generate BUILD files
bazel run //:gazelle

[!NOTE] For pytest suites, use py_pytest_test (always drives pytest) instead of the generic py_test. Because Gazelle can't infer the pytest dependency for assert-only tests, map py_test to a thin wrapper that injects it rather than mapping directly — see docs/test-drivers.md. py_pytest_test/py_unittest_test require a release that includes them (later than the 1.11.2 pinned above).

Migration from rules_python

aspect_rules_py is designed for incremental adoption:

1. Swap the rules: Load py_binary, py_library, py_test from @aspect_rules_py//py:defs.bzl instead of @rules_python//python:defs.bzl
2. Migrate dependencies: Replace pip.parse with uv.declare_hub and generate a uv.lock
3. Optionally migrate toolchains: Replace rules_python interpreter provisioning with the aspect_rules_py interpreter extension for fully independent hermetic interpreters

For detailed migration guidance, see docs/migrating.md.

Documentation

• Dependency resolution with uv
• Virtual dependencies
• Interpreter configuration
• Migration guide
• Contributing

Users

• OpenAI
• Physical Intelligence
• RAI Institute
• NVIDIA OSMO
• ZML
• Eclipse SCORE
• Intrinsic
• Enfabrica
• ReSim AI
• StackAV
• Netherlands Cancer Institute
• pyrovelocity

Architecture

Layer	Implementation	Description
Toolchains	@aspect_rules_py//py	Own python-build-standalone interpreter provisioning; @rules_python optional
Resolution	@aspect_rules_py//uv	Fast, lockfile-backed dependency resolution with uv
Execution	@aspect_rules_py//py	Drop-in replacements for py_binary, py_library, py_test with sandbox isolation
Generation	aspect-gazelle	Pre-compiled Gazelle extension—no CGO toolchain required

License

Apache 2.0 - see LICENSE