aspect gc

Bazel keeps one output base per workspace path, and the download cache, forever. Delete a git worktree and its output base, with its external/ tree and action cache, stays behind. aspect gc removes what nothing is using.

aspect gc --dry-run      # list what would go, delete nothing
aspect gc                # list, confirm, remove
aspect gc --force        # remove without asking (CI, cron)
aspect gc <hash>...      # remove these bases, whatever the rules say

What it removes

Rule	Removed once	Flag	Default
Orphaned output base: its workspace directory no longer exists	unused for the grace period	`--orphan-grace-hours`	1
Idle output base, whether or not its workspace exists	unused past the maximum idle time	`--base-max-idle-days`	30
Download cache entry (`cache/repos/v1/content_addressable`)	unused past the maximum idle time	`--download-cache-max-idle-days`	30
A `.gc-trash-*` directory an interrupted `gc` left behind	always

Each period takes 0: the grace period to remove orphans immediately, the idle cutoffs to turn their rule off. Everything removed is re-creatable: a removed output base costs a cold build, a pruned download one re-fetch. “Last used” is when a Bazel server last started or ran a command in the base. A download-cache entry’s last use is the newer of its mtime and atime, since Bazel touches the mtime on every cache hit.

What it keeps

An output base with a running Bazel server, unless it is orphaned. An orphan’s server is stopped before its base is removed.
An output base a process may be serving that ps cannot identify, as on an image without procps.
An aspect worktree pool slot’s base, which is not treated as orphaned: a free slot has no worktree on purpose, and that base is what makes its next lease warm.
The exception is a slot nothing will lease again, its directory gone and its pool holding no record of it. That base is an orphan like any other.
A pool slot’s base still goes by idle time, a leased slot’s included, since --base-max-idle-days measures Bazel’s use of the base and not whether a checkout is open. A removed base costs that slot a cold build, never its checkout.
Anything under the output user root that is not named like an output base, such as install/ and cache/.

Removing specific output bases

Name output bases to remove them instead of applying the rules, whatever their state. Each is a hash or a path under the output user root, and any number can be named at once. A running server in a named base is stopped first. The download cache is left alone, and no census is printed; the JSON still carries the policy, with no download-cache entries.

aspect gc d41d8cd98f00b204e9800998ecf8427e

aspect output-bases lists the hashes.

Removing every output base

--all removes every output base under the output user root, whatever its state — live, idle, orphaned, within the grace period, aspect worktree pool slots, undetermined and trash — as if each were named. A running Bazel server in one is confirmed as that base’s own and stopped first; the listing, the prompt and --dry-run say which, and mark the server of the workspace you run it from. A process ps cannot identify fails that base’s removal rather than being killed.

$ aspect gc --all --dry-run
INFO: Bazel output user root: ~/Library/Caches/bazel/_bazel_me
  scanning Bazel output bases…
  measuring sizes of 3 Bazel output bases…
  scanning the Bazel download cache…
  3 Bazel output bases to remove, 6 MB:
    3 MB  540b29d4073e3c9c6702541d05811ef8  (--all; live; workspace ~/src/web)
    2 MB  c84887dbc6585633e5acf6a25179882c  (--all; live; workspace ~/src/web)
    1 MB  e9a33320d289064646ca04497ef4fcec  (--all; live; workspace ~/src/web)
  would reclaim 6 MB; run without --dry-run to remove it

It never touches aspect worktree checkouts, leases or registries — a pool slot just starts cold — nor install/ or cache/repos/v1/contents, and the download cache keeps its --download-cache-max-idle-days rule. Only a directory holding one of DO_NOT_BUILD_HERE, execroot/, server/ or lock is taken; any other md5-named entry is listed as kept, and a root where none holds any, with no install/ beside them — an install/ directory passed as the root, say — is refused. --all cannot be combined with named bases. Off a terminal it needs --force; on one, the prompt states what it will do: “Remove all 58 Bazel output bases (91.2 GB), stopping 12 running Bazel servers?”

Confirmation

gc lists everything it will remove, with sizes, then asks. --force answers yes in advance and is required when stdin is not a terminal, so a gc in CI or cron states that it deletes.

$ aspect gc
INFO: Bazel output user root: ~/Library/Caches/bazel/_bazel_me
  scanning Bazel output bases…
  5 Bazel output bases: 2 live, 1 idle, 1 orphaned, 1 undetermined
    orphaned: the base's workspace directory no longer exists, e.g. a deleted worktree.
      `aspect gc` removes one 1h after last use (--orphan-grace-hours=N to change, 0 for immediately).
    undetermined: nothing in the base names its workspace, so it cannot be orphaned.
      `aspect gc` removes one 30d after last use (--base-max-idle-days=N to change, 0 to keep), or now with `aspect gc <hash>`.
    Run `aspect output-bases` to list the kept Bazel output bases (live, undetermined).
  measuring sizes of 2 Bazel output bases…
  scanning the Bazel download cache…
  2 Bazel output bases to remove, 3.3 GB:
    2.2 GB  7f18ea0edb2474de1526d9aa847f0ab9  (workspace gone: ~/src/web/.claude/worktrees/feat-search)
    1.1 GB  557089df67d989f705a1cf9794dcb086  (unused for 45d; workspace ~/src/api)
  Bazel download cache: 812 of 2,104 entries unused for 30d or more, 3.1 GB
  Delete 2 Bazel output bases and prune 812 Bazel download cache entries, freeing 6.4 GB? [y/N] y
  [1/2] removing 2.2 GB  7f18ea0edb2474de1526d9aa847f0ab9
  [2/2] removing 1.1 GB  557089df67d989f705a1cf9794dcb086
  pruning 812 Bazel download cache entries…
  reclaimed 6.4 GB

Each base is checked again just before it is removed and left alone if Bazel used it after the scan, so a build started while the prompt waited keeps its output base.

JSON

--output=json writes one document to stdout: the output user root, the policy, a count per state (pooled counting pool slots that are neither idle nor orphaned), each removal with its state, kb and outcome (reaped, skipped, failed, or not attempted under --dry-run or when the prompt is declined) and, where its base had a running server, server_stopped, download-cache totals, and what was freed. all says whether --all was given. kept lists the entries left alone as not output bases; both keys are always present, and kept is empty rather than absent when there is nothing to report. The exit code is non-zero when anything could not be removed. A run refused for want of --force off a terminal writes no document.

{
  "schema_version": 1,
  "output_user_root": "~/Library/Caches/bazel/_bazel_me",
  "dry_run": true,
  "policy": {"orphan_grace_hours": 1, "base_max_idle_days": 30, "download_cache_max_idle_days": 30, "bazel_output_bases": []},
  "counts": {"live": 2, "idle": 1, "orphaned": 1, "orphaned_within_grace": 0, "pooled": 0, "undetermined": 1, "trash": 0},
  "removals": [
    {"path": "~/Library/Caches/bazel/_bazel_me/7f18ea0edb2474de1526d9aa847f0ab9", "workspace": "~/src/web/.claude/worktrees/feat-search", "state": "orphan", "pid": 0, "last_used_ms": 1759359600000, "kb": 2306867, "outcome": "not attempted"},
    {"path": "~/Library/Caches/bazel/_bazel_me/557089df67d989f705a1cf9794dcb086", "workspace": "~/src/api", "state": "idle", "pid": 0, "last_used_ms": 1755644400000, "kb": 1153434, "outcome": "not attempted"}
  ],
  "download_cache": {"entries": 2104, "stale_entries": 812, "stale_kb": 3250586, "pruned": 0, "skipped": 0, "freed_kb": 0},
  "all": false,
  "kept": [],
  "reclaimable_kb": 6710887,
  "reaped": 0,
  "skipped": 0,
  "freed_kb": 0
}

Paths are shown here with ~; the document carries them in full.

Flags

Flag	Default
`--all`	`false`	Remove every output base under the root, stopping running servers; see removing every output base.
`--dry-run`	`false`	List what would be removed; delete nothing.
`--force`	`false`	Remove without asking. Required off a terminal.
`--orphan-grace-hours`	`1`	Hours an orphaned base is kept after its last use.
`--base-max-idle-days`	`30`	Days of disuse after which a base is removed. `0` turns this off.
`--download-cache-max-idle-days`	`30`	Days of disuse after which a download-cache entry is pruned. `0` turns this off.
`--output-user-root`	rc, then platform default	The output user root to collect.
`--output`	`text`	`text` or `json`.
`<hash>...`		Output bases to remove by name, whatever their age; see removing specific output bases.

Get started

Platform

Aspect Cloud

Aspect Enterprise

Aspect CLI

Bazel

Learning

What it removes

What it keeps

Removing specific output bases

Removing every output base

Confirmation

JSON

Flags

​What it removes

​What it keeps

​Removing specific output bases

​Removing every output base

​Confirmation

​JSON

​Flags

What it removes

What it keeps

Removing specific output bases

Removing every output base

Confirmation

JSON

Flags