proposal: cmd/go: add `-go` flag to `go mod init`

[sudomateo]

Proposal Details

I propose adding a -go flag to the go mod init command. This flag allows users to explicitly specify the Go language version used for the go directive in go.mod rather than relying on the toolchain's default heuristic.

Background

When a user runs go mod init [module-path], the Go toolchain automatically inserts a go directive into go.mod. The version selected is typically the version of the toolchain being used, or 1.(N-n).0 after #74748 shipped in Go 1.26.0.

If a developer wants to initialize a module that targets an older version of Go for compatibility reasons (e.g., a library intended to support the last two major Go releases), they must perform a two-step process.

go mod init [module-path]
go mod edit -go=X.Y.Z

This is counter-intuitive for an initialization command, as it forces the user to initialize with a default they don't want and then immediately edit it.

Proposal

Add a -go flag to the go mod init command.

go mod init [-go=version] [module-path]

Example usage.

go mod init -go=1.25.0 example.com/example

This would produce the following go.mod regardless whether the user is running Go 1.25.X, 1.26.X, or a release candidate.

module example.com/example

go 1.25.0

Rationale

The primary motivation is user experience and consistency.

• Library Authors: Many maintainers support the two most recent major releases of Go. When initializing a new module, they often want to decide on and set the Go version immediately (e.g., cmd/go: decide and document official recommendation for typical 'go' version in go.mod for open source libraries #77830).

• Consistency: The go mod edit command already supports a -go flag. Bringing this to go mod init makes the toolchain interface more consistent.

• Automation: Scripts that scaffold new Go projects would benefit from a single command setup.

Alternatives Considered

• Environment Variables: Users could set GOTOOLCHAIN, but this affects the entire execution environment and is overkill for simply writing a version string to a text file.

• Do Nothing: While functional, the two-step process is a minor friction point that has been raised in community discussions (e.g., cmd/go: change go mod init default go directive back to 1.N #77653).

Compatibility

This change is fully backwards compatible. When the -go flag is omitted, the command defaults to its current behavior. The flag follows the standard -go flag syntax used elsewhere in Go.

[mwriter]

It seems to me that we should also link this issue with #77830

[gabyhelp]

Related Issues

• cmd/go: change `go mod init` default go directive to 1.(N-n).0 #74748 (closed)
• proposal: cmd/go: change `go mod init` default go directive back to 1.N #77653
• cmd/go: go mod init should be able to specify go/toolchain version #61299 (closed)
• proposal: cmd/go: rename go mod init to go init #26801 (closed)
• proposal: cmd/go: mod init: option to infer module name from git origin #60635 (closed)
• cmd/go: document that Go 1.26rc1 go mod init creates a 1.24.0 module #76857 (closed)
• cmd/go: `mod edit -go` is incompatible with `env GOVERSION` and the `go/version` package #77888
• proposal: cmd/go: GOTOOLCHAIN=mod to use exact version of toolchain directive #69956 (closed)
• cmd/go: inconsistent behavior when 'go' directive is missing from 'go.mod' #44976 (closed)

Related Code Changes

• cmd/go: add go statement when initializing go.mod

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[hyangah]

What will be the relationship with go mod tidy's -go and -compat? Aren't we adding one more way to achieve the same thing?

[sudomateo]

What will be the relationship with go mod tidy's -go and -compat?

Siblings. go mod init will target new go.mod files and go mod tidy will target existing go.mod files.

Aren't we adding one more way to achieve the same thing?

Depends on the perspective really. No, there's no way to set the go.mod at initialization. Yes, one can use the two-step process outlined in the original comment or edit the go.mod file by hand.

[mwriter]

go mod tidy will

Probably the most implicit command in the toolchain that I stopped using altogether.

[dolmen]

Note that go mod init already has (at least) one undocumented flag: -modfile. See #78503 for details.