# Go Version Requirements and Automatic Toolchain Switching in go-modern-guidelines

> Discover go-modern-guidelines Go version requirements and how it uses GOTOOLCHAIN auto to switch toolchains. Learn about automatic toolchain switching.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: internals
- Published: 2026-08-30

---

**The go-modern-guidelines CLI requires Go 1.25 or newer, but remains fully functional on older Go installations by leveraging Go's `GOTOOLCHAIN=auto` feature to automatically download compatible toolchains.**

The `go-modern-guidelines` repository by JetBrains provides a CLI tool that analyzes Go projects against modern best practices. Understanding the **Go version requirements** and how the tool handles **automatic toolchain switching** ensures seamless operation across diverse development environments, even when the locally installed Go version predates the minimum requirement.

## Minimum Go Version Requirements

As documented in [`README.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/README.md) at lines 31-32, the CLI explicitly targets **Go 1.25 or newer**. However, the tool does not fail when executed on older Go installations. Instead, it relies on the Go toolchain's built-in version management capabilities to transparently fetch and execute a compatible runtime.

When the CLI initializes, it attempts to detect the target version from the project's `go.mod` file or an explicitly supplied file path. If no version is specified through CLI flags, the resolution logic queries the local environment to determine the base toolchain version.

## How Automatic Toolchain Switching Works

The CLI delegates version compatibility to Go's **automatic toolchain switching** mechanism, which operates when `GOTOOLCHAIN=auto` is set (the default). When the detected Go version is older than 1.25, the Go command automatically downloads and invokes a newer toolchain that satisfies the 1.25+ requirement, allowing the CLI to execute modern analysis features without manual intervention.

### Version Detection Implementation

In [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go) (lines 34-35), the version resolution implements the fallback logic that triggers toolchain switching:

```go
// From internal/goversion/goversion.go
// Falls back to local Go toolchain when no explicit version provided
version, err := getLocalGoVersion()

```

This function retrieves the current toolchain version via `go env GOVERSION`. If the returned version is insufficient, Go's `GOTOOLCHAIN=auto` behavior automatically acquires and executes a compatible toolchain before the CLI proceeds with guideline analysis.

### The GOTOOLCHAIN=auto Mechanism

When `GOTOOLCHAIN=auto` is enabled (the default setting), the Go command performs three steps:
1. **Detects** the required version from `go.mod` or CLI flags
2. **Compares** it against the currently installed toolchain
3. **Downloads** and executes a newer toolchain if the local version is below 1.25

This mechanism eliminates the need for developers to manually manage multiple Go installations while ensuring the CLI accesses the language features required for accurate guideline enforcement.

## Overriding the Default Behavior

Developers can bypass automatic detection by explicitly specifying a target version using the `--go-version` flag parsed in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go). This override takes precedence over both `go.mod` detection and local toolchain fallback:

```bash

# Force analysis against Go 1.27 regardless of local installation

$ go-modern-guidelines --go-version=1.27 list

```

Use this approach to preview guideline changes for newer Go versions before upgrading project dependencies, or to ensure consistent analysis across CI/CD pipelines with varying base images.

## Practical Usage Examples

Running the CLI on a system with Go 1.22 installed demonstrates the automatic switching behavior. The Go command automatically downloads a 1.25+ toolchain because `GOTOOLCHAIN=auto` is the default:

```bash
$ go-modern-guidelines list

# Prints modern guidelines using automatically fetched Go 1.25+ toolchain

```

To manually control the toolchain switching behavior:

```bash

# Explicitly enable auto-switching (redundant but explicit)

$ export GOTOOLCHAIN=auto
$ go-modern-guidelines list

# Or specify an exact version without relying on go.mod detection

$ go-modern-guidelines --go-version=1.26 list

```

## Summary

- The go-modern-guidelines CLI requires **Go 1.25 or newer** as documented in the README
- **Automatic toolchain switching** via `GOTOOLCHAIN=auto` ensures backward compatibility with older Go installations
- Version resolution in [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go) falls back to `go env GOVERSION` when no explicit version is provided
- Use the `--go-version` flag parsed in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) to override automatic detection
- The tool detects project versions from `go.mod` or accepts manual file paths via CLI arguments

## Frequently Asked Questions

### What happens if I run go-modern-guidelines with Go 1.21 installed?

The tool executes successfully because Go's `GOTOOLCHAIN=auto` setting (enabled by default) automatically downloads and uses a Go 1.25+ toolchain to satisfy the requirement. According to lines 31-32 of [`README.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/README.md), the CLI remains functional on older versions through this automatic switching mechanism rather than failing with a version error.

### How does the tool determine which Go version to analyze against?

As implemented in [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go), the resolution logic follows a priority order: first checking the `--go-version` CLI flag, then parsing the version from the project's `go.mod` file, and finally falling back to the local toolchain version reported by `go env GOVERSION` (lines 34-35). This detected version drives both the guideline selection and triggers automatic toolchain acquisition if needed.

### Can I disable automatic toolchain switching?

Yes, by setting `GOTOOLCHAIN=local` before running the CLI. However, if your local installation is below version 1.25, the tool may encounter compatibility issues or fail to access required analysis features. The recommended approach is to either upgrade your local installation to Go 1.25+ or allow the automatic switching to function with the default `GOTOOLCHAIN=auto` setting.

### Where is the minimum version requirement documented?

The requirement for Go 1.25 or newer is explicitly stated in the [`README.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/README.md) file at lines 31-32, which clarifies that the CLI targets Go 1.25+ while remaining functional on older versions through automatic toolchain switching when `GOTOOLCHAIN=auto` is enabled.