Packages, project layout and dependencies

Package naming and internal packages, cmd and pkg layout, adding and upgrading modules, vendoring, and semantic import versioning.

Packages and internal

A package is a directory. Every file in it declares the same package name, and the whole package is compiled as a unit, so files can share unexported identifiers freely.

notes/
  go.mod
  cmd/notes/main.go        package main   -> import path example.com/notes/cmd/notes
  internal/store/store.go  package store  -> importable only inside example.com/notes
  internal/config/config.go
  user.go                  package notes  -> the public surface of the library
  user_test.go

• Name packages after what they provide, not after a layer: store, auth, pricing — not util, common or helpers, which attract unrelated code forever.
• Do not repeat the package name in identifiers. store.Store is fine; store.StoreStore is not. http.Server and bytes.Buffer read well because the qualifier and the name differ.
• Everything under internal/ can be imported only by packages rooted at that directory's parent. It is enforced by the compiler and is the correct way to keep an API private while still splitting code across directories.
• Avoid a deep hierarchy of tiny packages. Dependencies flow one way, and a package that imports thirty others is usually two packages.

Choosing a layout

// cmd/notes/main.go — the only place that knows the whole application
package main

import (
    "example.com/notes/internal/config"
    "example.com/notes/internal/store"
)

func main() {
    cfg, err := config.Load("config.toml")
    if err != nil {
        log.Fatal(err)                 // logging at the boundary, once
    }
    s := store.New(cfg.DatabaseURL)
    run(context.Background(), cfg, s)
}

When the same library grows a second binary, promote the shared wiring into a package and keep the cmd files to flags plus one call. That is the whole test for a layout: can a new binary be added without moving code?

Dependencies and versioning

go get github.com/spf13/[email protected]     # pin an exact version
go get -u=patch ./...                    # apply patch upgrades only
go list -m -u all                        # what could be upgraded
go mod why github.com/some/dep           # why it is required at all
go mod verify                            # check the cache against go.sum
go mod vendor
go build -mod=vendor ./...               # build from vendor/, no network

• Semantic import versioning: a module at v2 or above carries the major version in its path — github.com/x/y/v2. Two majors can therefore be required at once without conflict.
• A // indirect comment means nothing in your code imports that module directly; it is present because a dependency needs it. Do not hand-edit those lines.
• Vendoring commits the dependency source into the repository. It makes builds work without a proxy and makes review show exactly what changed, at the cost of a large diff.
• Upgrade deliberately and in one commit per dependency group, then run the full test suite. Bulk -u ./... upgrades are how a working service picks up three breaking changes at once.
• The minimum version selection rule means Go never surprises you with a newer version than go.mod names — you always get the versions you asked for.

FAQ

Related

Setting up Go: modules, toolchain and editors Profiling, performance and deployment

Last refreshed 2026-09-18.