In the go command, what do -mod=mod, -mod=readonly and -mod=vendor do, and which applies by default?

## One flag, two decisions The `-mod` flag is accepted by the build-ish `go` subcommands — `go build`, `go test`, `go run`, `go list`, `go vet` and friends. It controls **where imports are resolved from** and **whether `go.mod` may be modified as a side effect of building**. There are three values. ### `-mod=mod` The original behaviour of modules. The build resolves imports against the module graph, and if it encounters an import that no requirement in `go.mod` provides, it works out which module provides it, adds a `require` line, and carries on. `go.mod` (and the recorded hashes) are updated as a side effect of an ordinary build. This is convenient and was the source of a real class of problem: a build could change your dependency set. Two engineers running `go build` on the same commit could end up with different `go.mod` files, and a stray import in a scratch file could quietly add a dependency nobody reviewed. ### `-mod=readonly` The default since Go 1.16. The `go` command may **read** `go.mod` but not write it. If the build needs something the file does not already provide, the command stops with an error that names the exact `go get` invocation that would fix it. Dependency changes become an explicit act, performed by a command whose whole job is to change dependencies, rather than a side effect of compiling. This is why, on a modern Go toolchain, `go build` never surprises you by editing a tracked file — and why a missing requirement shows up as a build failure with a suggested command rather than as a diff. ### `-mod=vendor` A different source of truth entirely. Imports resolve from the `vendor/` directory at the module root; the module cache and the network are not consulted. An import with no package under `vendor/` fails immediately rather than triggering a lookup, because import lookup is disabled in this mode. `go.mod` is not modified. Before building, the `go` command cross-checks `vendor/modules.txt` against `go.mod` and refuses to start if they disagree, so vendor mode cannot silently build against a dependency set that does not match the module requirements. ## How the default is chosen The default is `readonly` — **unless** the main module has a `vendor` directory and its `go.mod` declares `go 1.14` or later, in which case the default is `vendor`. Nobody configures this; it follows from the directory existing. That is a deliberate design choice (vendoring should just work for anyone who clones the repository) with an important consequence: adding `vendor/` to a repository changes how everyone's builds resolve packages, whether or not they noticed the directory. ## Overriding Because the vendor default is inferred rather than declared, you sometimes need to override it: ``` go build -mod=readonly ./... ``` This builds the same code against the module cache while leaving `vendor/` untouched on disk. It is the standard way to answer "is this failure caused by my code, or by a stale vendored tree?" — if the build succeeds with `-mod=readonly` and fails without it, the vendored source is the problem. The reverse case matters too. If you want vendor mode to be an explicit, checked property of your build rather than a consequence of whether the directory happens to be checked out, set it in the environment: ``` GOFLAGS=-mod=vendor ``` `GOFLAGS` applies its contents to every `go` command that accepts them. Setting it in CI makes the intent visible in the build configuration, and turns "someone deleted vendor/" into a loud failure rather than a silent switch back to the module cache. ## What each value does not do - `-mod=readonly` does not make the module cache read-only, and does not stop downloads; it only forbids editing `go.mod`. - `-mod=vendor` does not fetch anything, ever, and does not regenerate the vendor directory. Only `go mod vendor` writes that tree. - `-mod=mod` does not delete or bypass `vendor/`; it simply ignores it for that command, leaving the directory in place. ## Choosing in practice Most repositories want the default. Vendored repositories want the vendor default, ideally made explicit in CI. `-mod=mod` is best treated as a deliberate, occasional act rather than a habit — if you find yourself reaching for it to make a build pass, the honest fix is usually a `go get` that updates requirements on purpose.