Output Root

After your first bazel build, new entries appear at the workspace root — not source files, but convenience symlinks pointing into Bazel's output directory hierarchy¹. Bazel never writes build artifacts into the source tree². All outputs go to a separate directory, and the symlinks provide quick access to find them.

The Convenience Symlinks

Four symlinks appear alongside MODULE.bazel (0.1.2 Repository Root) and your BUILD.bazel files¹:

my-project/
├── MODULE.bazel
├── BUILD.bazel
├── app/
│   ├── BUILD.bazel
│   └── main.cc
├── bazel-bin → ...            ← compiled outputs
├── bazel-my-project → ...     ← execution root
├── bazel-out → ...            ← raw output root
└── bazel-testlogs → ...       ← test logs

These symlinks are for your convenience only — Bazel does not use them internally¹. They point into the output base, a per-workspace directory that Bazel manages outside your source tree.

Path Mirroring

Output paths mirror the package structure (0.1.3 Package): the package part of the label becomes the subdirectory under Bazel's output trees. Most targets have one main output location. Tests are the common exception: Bazel builds the test program under bazel-bin/, then writes execution artifacts such as logs and XML under bazel-testlogs/¹.

The diagram below shows one runnable example, reproduced by the output-path-mirroring snippet. The sample files are representative, not exhaustive: real output directories often include helper files such as params files or test metadata.

That is why tests break the simple "one label -> one final file" mental model: one test target can have a built test executable in bazel-bin/ and a separate per-target artifact directory in bazel-testlogs/¹.

Configurations Inside bazel-out

Inside bazel-out/, Bazel creates a subdirectory for each build configuration — a combination of target platform, compilation mode, and other settings¹:

bazel-out/
├── k8-fastbuild/
│   ├── bin/                ← compiled outputs (BINDIR)
│   └── testlogs/           ← test results
├── k8-opt/
│   ├── bin/
│   └── testlogs/
└── _tmp/
    └── actions/            ← stdout/stderr from build actions

The bazel-bin and bazel-testlogs symlinks point to one configuration at a time: the configuration of your most recent top-level build or test. Change flags such as -c opt, build for a different platform, or switch to a top-level target with a different configuration, and those symlinks may point somewhere else. Older outputs still remain in bazel-out/.

If you need the full picture, look in bazel-out/. It keeps one subtree per configuration, while bazel-bin and bazel-testlogs are just shortcuts into one of them.

Why Outputs Live Outside the Source Tree

Bazel stores all outputs in a directory derived from an MD5 hash of the workspace root path, located under ~/.cache/bazel/ on Linux or ~/Library/Caches/bazel/ on macOS³. This isolation ensures that³:

• Multiple users on a shared machine don't collide — each user gets a separate output root.
• Multiple workspaces each get their own output base, even for the same project checked out in different paths.
• Multiple configurations coexist under bazel-out/ without overwriting each other.

You can inspect these paths with bazel info²:

$ bazel info output_base
/home/user/.cache/bazel/_bazel_user/7ffd56a6e4cb724ea575aba15733d113

bazel clean removes the output path and action cache. bazel clean --expunge removes the entire output base, including server state and fetched external dependencies³.

Gitignoring Output Directories

The convenience symlinks should be excluded from version control:

/bazel-*

This catches all four convenience symlinks: bazel-bin, bazel-out, bazel-testlogs, and bazel-<project-name>¹.

~/.cache/bazel/                               ← outputRoot
└── _bazel_$USER/                             ← outputUserRoot
    ├── install/
    │   └── <md5-of-bazel-install>/           ← installBase
    └── <md5-of-workspace-path>/              ← outputBase
        ├── action_cache/                     ← persistent action cache
        ├── external/                         ← fetched external repos
        ├── server/                           ← Bazel server state
        └── execroot/
            └── _main/                        ← execRoot
                └── bazel-out/                ← outputPath