Imports, goimports, and go mod tidy

Every pull request in a busy Go repo conflicts in the same place: the import block. Two developers add different packages to the same file, git cannot merge both insertions, and the resolution is mechanical. The conflict reveals what the block actually is — a file's declaration of the packages it depends on, ordered by convention so a reviewer sees the dependency edges without reading the body.

package checkout

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/stripe/stripe-go/v82"
	"golang.org/x/sync/errgroup"

	"example.com/shop/inventory"
	"example.com/shop/orders"
)

Three groups, each alphabetized, each separated by a blank line: the standard library, third-party modules, and packages from your own module. The grouping is not enforced by gofmt — the formatter never reorders your imports. Teams adopt it because a reviewer glancing at the block learns instantly whether a change introduces a network dependency or stays in the standard library. Conflicts also shrink: developers editing different groups no longer collide.

Two facts hide inside each import line. First, the import path and the package name are different things. The identifier you write comes from the package clause inside the source file, which usually — but not always — matches the last path segment:

import (
	"database/sql"            // package name: sql
	"github.com/go-sql-driver/mysql" // package name: mysql
	"gopkg.in/yaml.v2"        // package name: yaml (path ends in v2)
)

When two imported packages share a name, alias one. Alias only on collision; gratuitous aliases make readers check the mapping twice.

Second, an unused import is a compile error, not a warning. Go refuses to build a block that disagrees with the body, which means a stale import after a refactor breaks the build the moment it exists instead of lingering for months. That strictness is also why tooling can safely manipulate the block: if the code compiles, every import in the block is used, and every package the code names must be importable. Keeping those two directions in sync is mechanical work, and mechanical work belongs to tools — which is where gofmt, goimports, and the module commands come in.

A refactor just landed: a helper package was deleted and a new JSON field added. On the author's machine the build is green; on a teammate's fresh clone it fails with undefined: json.MarshalIndent. The code says json.MarshalIndent, the import block does not say encoding/json, and nobody wants to hand-edit blocks on fifty files. Two tools exist for this, and they do different jobs.

gofmt reformats source to the canonical layout and touches nothing else:

gofmt -l .      # print files whose formatting differs; empty output = clean
gofmt -w .      # rewrite them in place

It never adds or removes imports. After the refactor above, gofmt -w leaves the missing import missing.

goimports is gofmt plus import hygiene. It parses each file, works out which imports the body uses, drops the unused ones, and adds the ones it can resolve:

// before: uuid is no longer referenced, json is now referenced
import (
	"os"

	"github.com/google/uuid"
)

// after `goimports -w .`
import (
	"encoding/json"
	"os"
)

Because it needs to know which packages exist, run it inside a module — it consults the module's requirements and cache to resolve third-party names, and it resolves standard library names unconditionally.

The one flag worth memorizing is -local, which routes your own module's packages into their own trailing group:

goimports -local example.com/shop -w .

Now the block always reads stdlib, third-party, yours — on every machine, regardless of who saved last. Wire both checks into CI so formatting never becomes a review comment:

test -z "$(gofmt -l .)" || { gofmt -l .; exit 1; }
out=$(goimports -local example.com/shop -l .) && test -z "$out" || { echo "$out"; exit 1; }

One honest limitation: goimports resolves by name. If two modules export the same identifier, it can guess wrong, so read the diff of any import change it makes. A wrong import fails compilation loudly, which is the acceptable failure mode — but you still want the diff in review, not just in your editor.

A fresh clone fails to build: no required module provides package github.com/pkg/errors; to add it: go get github.com/pkg/errors. The author's editor auto-imported the package weeks ago with -mod=mod, quietly updated their local go.mod, and the change was never committed. The teammate's checkout has the new import and the old requirement list. Two files must move together — go.mod declares the requirements, go.sum records the hashes that prove them — and only one made it into the commit.

go mod tidy reconciles both files with the source:

go mod tidy     # add missing requirements, drop unused ones, refresh go.sum
go mod verify   # check the module cache against go.sum hashes
go get github.com/acme/logfmt@v1.4.0  # pin a chosen version on purpose

What tidy scans is the part people underestimate. It walks every package in the module — including the imports inside test files — resolves each import path to a module, adds requirements for modules nothing declared (marked // indirect when they are only transitive), removes direct requirements nothing imports anymore, and regenerates go.sum entries for the versions it now considers. A library imported only by a _test.go file still counts; tidy will keep its requirement alive.

Deliberate version choices survive tidy: it adds requirements for what is missing and removes what is unused, it does not gratuitously upgrade what is already required. Use go get pkg@vX.Y.Z when you want a specific version, and tidy will leave it alone as long as the code still imports it.

For CI failures, the diagnosis fits in a table:

The discipline that prevents all three: run tidy after any import change and commit go.mod and go.sum in the same commit as the import. Neither file is hand-edited — hashes in go.sum are computed, and manual entries fail verification. What tidy cannot tell you is which version you should require, how a dependency's requirements combine into the final build, or why a v2 library needs a new import path — that is the subject of go.mod and Semantic Versioning. The import blocks themselves follow from Packages and Exported Identifiers.