3.1.4 Legacy WORKSPACE Model

Legacy WORKSPACE is the dependency model behind most pre-Bzlmod Bazel guides and many brownfield repositories. Instead of declaring a module graph and resolving it collectively, the main repo bootstraps external repositories by executing repo rules in WORKSPACE, often followed by load()ed setup macros.^1,2 You still need that mental model when reading older docs, understanding why a repo behaves differently from 3.1.1 Bzlmod (MODULE.bazel), or deciding what still has to move into M1 WORKSPACE → Bzlmod.

What to Recognize in Old Docs

A typical legacy setup introduced each external repository directly in WORKSPACE:¹

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "foo",
    urls = ["https://example.com/foo.zip"],
    sha256 = "c9526390a7cd420fdcec2988b4f3626fe9c5b51e2959f685e8f4d170d1a9bd96",
)

In real repositories that stanza was often followed by more load() statements from the downloaded repo and helper macros like *_dependencies() or *_toolchains().^1,2 That is the big difference from 3.1.1 Bzlmod (MODULE.bazel): WORKSPACE behaved more like an imperative bootstrapping script than a declarative dependency manifest.

That model scaled badly. Bazel did not evaluate the WORKSPACE files of your dependencies, so transitive repos had to be recreated in the main repo or hidden behind layered deps.bzl macros.¹ Because the file is evaluated sequentially, macro order could also affect which transitive dependency version actually got used.^1,2 The same load()-driven shape is why brownfield repos still run into the fetch behavior discussed in 3.1.5 Eager Fetch Anti-pattern.²

Why It Still Shows Up

Legacy WORKSPACE is no longer the direction of travel, but it is not gone yet. Bazel 8 turned it off by default, and Bazel 9 removes it, yet older tutorials, partially migrated rulesets, and long-lived internal repos still depend on it.^2,3 Some projects also keep an empty or comment-only WORKSPACE file around because older tools still look for it as a repository boundary marker even after real dependency logic moved elsewhere.^1,4 If that is the only role the file still plays, the root-marker part of the story was introduced earlier in 0.1.2 Repository Root.

Coexistence Is the Real Brownfield Problem

When both systems are enabled, the practical question is not "which file runs first?" but "what does @name resolve to from this repository?" In the main repo, names introduced by the root MODULE.bazel win first, and Bazel falls back to WORKSPACE repos only when no Bzlmod mapping claims that name.⁵ But repositories in the Bzlmod world do not see WORKSPACE-defined repos at all.^2,5

That asymmetry is where mixed-mode bugs hide. A label may still work from the main repo while failing from a module dependency or extension-generated repo. If WORKSPACE.bzlmod exists, Bazel uses it instead of WORKSPACE when Bzlmod is enabled, which makes it a useful scratchpad for the legacy repos you have not migrated yet.^2,6

Brownfield Hygiene

Treat legacy WORKSPACE as inventory, not as the place where new dependency logic should keep growing. Keep a short record of which targets or rulesets still rely on WORKSPACE-only repos, migrate direct dependencies one by one, and remove duplicate declarations once a dependency is stable in MODULE.bazel.^2,4 Duplicating the same dependency path in both worlds is how "polluted workspace" failures happen: an older repo definition from WORKSPACE can unexpectedly survive long enough to shadow or conflict with the migrated setup.^4,6

If you actively need to support both dependency modes for consumers, the detailed tactics live in M1.3 Dual Compatibility (WORKSPACE + Bzlmod). This article's job is smaller: recognize the old pattern, understand the visibility trap, and keep the remaining WORKSPACE surface area contained. The full reference and migration playbook is M1 WORKSPACE → Bzlmod.