> ## Documentation Index
> Fetch the complete documentation index at: https://bazel.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Starlark flag scoping

This page explains how to restrict where [user-defined Starlark build
settings](https://bazel.build/extending/config.md#user-defined-build-settings) propagate in the
dependency graph using the `scope` and `on_leave_scope` attributes.

## Overview

When you set a flag on the command line or modify it in a [configuration
transition](https://bazel.build/extending/config.md#user-defined-transitions), every transitive
dependency inherits that flag value unless another transition changes it.

Unrestricted flag propagation causes two build performance problems:

1. **Out-of-project configuration forks (`ST-<hash>`)**: When a project defines
   a flag intended only for its own targets (for example,
   `//my_project/flags:enable_feature_x`) and modifies it in a rule or
   attribute transition, that flag remains in the configuration when
   dependencies cross into shared libraries outside the project. Because the
   configuration hash includes all non-default Starlark options, Bazel
   re-analyzes and rebuilds shared dependencies in a separate `ST-<hash>`
   output directory, reducing remote cache hit rates and increasing memory and
   CPU usage.
2. **Unnecessary exec tool rebuilds**: When a target-specific flag propagates
   across an `exec` transition to build tools (such as compilers, code
   generators, or linters), changing the flag forks the `exec` configuration
   and forces Bazel to rebuild those tools.

When a dependency moves outside a flag's declared `scope`, Bazel automatically
resets or removes the flag so downstream targets share a single canonical
configuration.

## Supported scopes at a glance

| Scope value | Target dependencies (in project) | Target dependencies (outside project) | Across `exec` transitions | Typical use case |
| :- | :- | :- | :- | :- |
| **`"target"`** *(default in Skylib)* | Keeps value | Keeps value | Resets to `build_setting_default` (or to the static `on_leave_scope` value, if set) | Standard flags that affect target outputs across the build graph without forking `exec` tools. |
| **`"project"`** | Keeps value | Resets transitioned value to baseline configuration value (or removes it if unset in baseline) | Preserves value across the `exec` transition, then enforces project boundaries on the `exec` target's package | Project-specific flags that must not fork shared libraries or external `exec` tools. |
| **`"universal"`** | Keeps value | Keeps value | Keeps value | Flags that must affect both target builds and all `exec` tools (for example, repository-wide `--incompatible_*` or toolchain-wide toggles). |
| **`"exec:--//pkg:host_flag"`** | Keeps value | Keeps value | Inherits the target-configuration value of `--//pkg:host_flag` | Flags paired with a separate host-side flag so you can override target and `exec` values independently on the command line. |

## Declare a scoped flag

### Predefined flag rules

You can set `scope` directly on Bazel's built-in and Skylib build setting rules:

* **Skylib build settings** ([`common_settings.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/rules/common_settings.bzl)):
  `bool_flag`, `string_flag`, `int_flag`, `string_list_flag`,
  `repeatable_string_flag`, and their `*_setting` counterparts include `scope`
  (defaulting to `"target"`). They do not expose `on_leave_scope`.
* **Native [`label_flag` and `label_setting`](https://bazel.build/extending/config#label-typed-build-settings)**:
  Support both `scope` and `on_leave_scope` (for `"target"`-scoped flags).

```python theme={null}
# my_project/flags/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "bool_flag", "string_flag")

string_flag(
    name = "release_channel",
    build_setting_default = "dev",
    scope = "project",
    values = ["dev", "alpha", "prod"],
    visibility = ["//visibility:public"],
)

bool_flag(
    name = "instrument_exec_tools",
    build_setting_default = False,
    scope = "universal",
)

label_flag(
    name = "custom_malloc",
    build_setting_default = "//base:default_malloc",
    on_leave_scope = "//base:host_malloc",
    scope = "target",
)
```

### Custom build setting rules

If you write a custom Starlark `rule(build_setting = ...)` instead of using a
predefined flag type, add `"scope": attr.string(...)` (and optionally
`"on_leave_scope"` with the same attribute type as `build_setting`) to your
rule's `attrs` dictionary:

```python theme={null}
# my_project/flags/build_defs.bzl
BuildSettingInfo = provider(fields = ["value"])

def _custom_flag_impl(ctx):
    return BuildSettingInfo(value = ctx.build_setting_value)

custom_string_flag = rule(
    implementation = _custom_flag_impl,
    build_setting = config.string(flag = True),
    attrs = {
        "scope": attr.string(
            default = "target",
            doc = "Controls where this flag propagates ('target', 'project', 'universal', or 'exec:--<flag>').",
        ),
        "on_leave_scope": attr.string(
            doc = "Optional value to set when a 'target'-scoped flag crosses an exec transition.",
        ),
    },
)
```

> [!NOTE]
>
> If your custom rule sets a rule-level default other than `"target"` (such as
> `default = "universal"` or `default = "project"`), pass `scope` explicitly on
> each target in `BUILD` if your Bazel version does not yet propagate rule-level
> `scope` defaults for command-line flags.

## Scope types in detail

### Project scope

Setting `scope = "project"` restricts a flag's non-baseline value to targets
belonging to the project that owns the flag.

#### Define the project boundary with PROJECT.scl

When a flag has `scope = "project"`, Bazel looks for a `PROJECT.scl` file in the
same package as the flag's `BUILD` file (or the nearest parent package) and
reads the default project directories from the `project` definition:

```python theme={null}
# my_project/flags/PROJECT.scl
project = {
    "active_directories": {
        "default": [
            "//my_project/app",
            "//my_project/flags",
            "//my_project/libs",
        ],
    },
}
```

```python theme={null}
# my_project/flags/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")

string_flag(
    name = "flavor",
    build_setting_default = "default",
    scope = "project",
    visibility = ["//visibility:public"],
)
```

#### Target dependencies

When a Starlark transition modifies a `scope = "project"` flag away from its
top-level baseline value, Bazel checks whether the target's canonical label
starts with any path listed in the project's default directories:

* **In-scope target** (for example, `//my_project/app:main` or
  `//my_project/libs/foo:bar`): The target keeps the flag's transitioned
  value.
* **Out-of-scope target** (for example, `//common/logging:logger` or an
  external repository target):
  * If `//my_project/flags:flavor` is not explicitly set in the top-level
    baseline configuration, Bazel removes `//my_project/flags:flavor` from
    the target's configuration, reverting it to `build_setting_default`.
  * If `//my_project/flags:flavor` is explicitly set in the top-level
    baseline configuration (for example, on the command line or via
    `PROJECT.scl` configs), Bazel resets `//my_project/flags:flavor` from
    the transitioned value back to its top-level baseline value.
  * If all transitioned flags on the target reset to the baseline
    configuration, the out-of-scope target returns to the unforked baseline
    configuration with no `ST-<hash>` suffix.

> [!NOTE]
>
> If no `PROJECT.scl` exists or `active_directories` is empty, Bazel treats all
> targets as out of scope and resets any transitioned value to the top-level
> baseline value (even for targets in the flag's own package).

#### Exec transitions

Unlike `scope = "target"`, a `project`-scoped flag does not automatically reset
on an `exec` transition. Instead, Bazel preserves its value across the `exec`
transition and evaluates the project boundary check against the `exec` tool
target's own label:

* **In-project `exec` tool** (for example, `//my_project/app:main` has an
  `exec` dependency on a code generator `//my_project/libs/codegen:gen` inside
  the project's directories): `//my_project/libs/codegen:gen` retains the
  custom value of `//my_project/flags:flavor`.
* **Out-of-project `exec` tool** (for example, `//my_project/app:main` has an
  `exec` dependency on an external compiler or code generator outside the
  project's directories): Bazel resets `//my_project/flags:flavor` on that
  tool to its baseline or default value, avoiding unnecessary host tool
  rebuilds.

### Target scope and on\_leave\_scope

`scope = "target"` is the default scope for all flags defined with Skylib's
`common_settings.bzl` (and for all Starlark flags when
`--incompatible_exclude_starlark_flags_from_exec_config=true`):

* The flag propagates across all target-configured dependencies
  (`cfg = "target"`).
* When crossing an `exec` transition (`cfg = "exec"`), Bazel excludes the flag
  from the `exec` configuration so that host tools see
  `build_setting_default`.

#### Customize the exec reset value with on\_leave\_scope

`on_leave_scope` applies only to `scope = "target"` flags (and is ignored by
`"project"` and other scopes). If an `exec` tool requires a fixed non-default
value when a customized `target`-scoped flag crosses an `exec` transition, set
`on_leave_scope` on a `label_flag`, `label_setting`, or custom `build_setting`
rule:

```python theme={null}
# my_project/flags/BUILD
load("//my_project/flags:build_defs.bzl", "custom_string_flag")

custom_string_flag(
    name = "sanitization_mode",
    build_setting_default = "full",
    on_leave_scope = "minimal_host",
    scope = "target",
)
```

When you set `//my_project/flags:sanitization_mode` to a non-default value (for
example, `--//my_project/flags:sanitization_mode=strict`):

* Target-configured rules read `"strict"`.
* Exec-configured rules read `"minimal_host"` (from `on_leave_scope`).

**Choose between `on_leave_scope` and `scope = "exec:--<host_flag>"`**:

* Use **`on_leave_scope`** when you have a single flag and `exec` tools should
  always receive a fixed constant defined in `BUILD` (not overridable on the
  command line).
* Use **`scope = "exec:--<host_flag>"`** (see [Cross-flag exec
  mapping](#cross-flag-exec-mapping)) when users or `.bazelrc` configs need to
  override target and `exec` values independently on the command line, or when
  using Skylib's `common_settings.bzl` rules (which do not expose
  `on_leave_scope`).

### Universal scope

A flag with `scope = "universal"` propagates its value everywhere in the build
graph, including across `exec` transitions and into external packages. Only an
explicit Starlark configuration transition that writes to the flag can change
its value.

```python theme={null}
# my_project/flags/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "bool_flag")

bool_flag(
    name = "incompatible_strict_validation",
    build_setting_default = False,
    scope = "universal",
)
```

> [!WARNING]
>
> Use `scope = "universal"` sparingly. Every change to a `universal` flag
> invalidates the `exec` configuration and forces Bazel to rebuild all host/`exec`
> tools (such as compilers and protocol buffer plugins) in that subgraph.

### Cross-flag exec mapping

Some workflows pair a target flag with a separate host/`exec` flag so you can
configure target and `exec` behavior independently on the command line (unlike
`on_leave_scope`, which hardcodes a single static literal in `BUILD`). Setting
`scope = "exec:--<another_flag_label>"` instructs Bazel to assign the
target-configuration value of `--<another_flag_label>` to this flag whenever
transitioning to an `exec` configuration.

```python theme={null}
# my_project/flags/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")

string_flag(
    name = "launcher",
    build_setting_default = "default_target_launcher",
    scope = "exec:--//my_project/flags:host_launcher",
)

string_flag(
    name = "host_launcher",
    build_setting_default = "default_host_launcher",
    scope = "target",
)
```

Register a `--flag_alias` for the host flag in `.bazelrc` (or on the command
line) so Bazel's option parser resolves the candidate flag:

```bash theme={null}
# .bazelrc
build --flag_alias=host_launcher=//my_project/flags:host_launcher
```

Run a build passing both flags:

```bash theme={null}
bazel build //my_project:app \
    --//my_project/flags:launcher=custom_target \
    --//my_project/flags:host_launcher=custom_host
```

* Target-configured rules reading `//my_project/flags:launcher` receive
  `"custom_target"`.
* Exec-configured rules reading `//my_project/flags:launcher` receive
  `"custom_host"` (or `"default_host_launcher"` if
  `--//my_project/flags:host_launcher` is omitted), without creating an
  `ST-<hash>` fork on the `exec` configuration when neither flag is
  customized.

## Verify flag scopes

You can inspect how Bazel scopes flags across in-project targets, out-of-project
targets, and `exec` targets using [`bazel cquery`](https://bazel.build/query/cquery) and `bazel
config`:

1. Query the configured dependency graph of your target:

   ```bash theme={null}
   bazel cquery 'deps(//my_project/app:main)'
   ```

   ```text theme={null}
   //my_project/app:main (a1b2c3d4...)
   //my_project/libs:helper (a1b2c3d4...)
   //common/logging:logger (e5f6g7h8...)
   ```

2. Inspect the configuration of an in-scope target versus an out-of-scope
   target using each target's configuration hash prefix:

   ```bash theme={null}
   bazel config a1b2c3d4
   ```

   ```text theme={null}
   BuildConfigurationValue a1b2c3d4...
   ...
   FragmentOptions user-defined {
     //my_project/flags:flavor: custom
   }
   ```

   ```bash theme={null}
   bazel config e5f6g7h8
   ```

   *(Omits `//my_project/flags:flavor` if it was set via transition and
   dropped outside `active_directories`, or shows the baseline value.)*

## Further reading

* [Configurations](https://bazel.build/extending/config.md)
* [Configurable build attributes](https://bazel.build/docs/configurable-attributes.md)
* [Configured query (cquery)](https://bazel.build/query/cquery.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.