← All notes

Summary

Packages group related Go code. Modules group packages and record what they need to build. go.mod at the module root lists the module path, the Go version, and required modules. go mod init creates it. go get and go mod tidy keep it aligned with your imports.

Start a module

Make a directory and run go mod init with a module path. The tutorial uses example.com/greetings. Publishable paths should be downloadable, usually the repository. Otherwise use a prefix you control, not a generic word like widgets. go.mod starts with the module name and Go version, then records dependency versions so builds stay repeatable. The sample package exports Hello because the name starts with a capital letter. A lowercase name stays inside the package.

Dependencies

An imported external package is a dependency, shipped as a module. Copy its path from pkg.go.dev into an import. go get . adds requirements for the current directory. go get plus a module path adds that module. Each require line is the minimum version you depend on. The download is cached and checked against the published module. A mismatch is a security error. go.sum stores checksums. Commit go.mod and go.sum.

Ask for a version with @ and the version, or @latest. go list -m -u all prints each dependency beside the newest version available. go mod tidy adds modules your imports need and removes modules nothing imports. -v prints removals. go get with @none drops one module and the requirements that existed only for it.

For unpublished code, require a stand-in version and replace it with a local directory or your fork, using go mod edit -replace and a matching go get. Imports stay on the original path. replace skips the usual authentication check. @ plus a commit or branch records a pseudo-version. go get -tool adds a tool directive; go tool runs it. GOPROXY lists download URLs, proxy first then direct. A comma tries the next URL only after HTTP 404 or 410. GOPRIVATE lists prefixes that must not use a proxy.

Claims

• id: C1 claim: A module collects one or more related packages and records the dependencies your code needs, including the Go version. source: S1 evidence: "In a module, you collect one or more related packages for a discrete and useful set of functions."
• id: C2 claim: go mod init writes a go.mod file that tracks the module name and, as you add them, dependency versions. source: S1 evidence: "The go mod init command creates a go.mod file to track your code's dependencies."
• id: C3 claim: A function whose name starts with a capital letter can be called from another package; that is an exported name. source: S1 evidence: "In Go, a function whose name starts with a capital letter can be called by a function not in the same package."
• id: C4 claim: External packages you import are dependencies, and Go distributes those packages as modules. source: S2 evidence: "When your code uses external packages, those packages (distributed as modules) become dependencies."
• id: C5 claim: A require directive in go.mod records the minimum version of a module your module depends on. source: S2 evidence: "A require directive tracks the minimum version of a module that your module depends on."
• id: C6 claim: go mod tidy adds missing modules required by your imports and removes modules your code no longer uses. source: S2 evidence: "this command edits your go.mod file to add modules that are necessary but missing."

@misc{iil_note_e6mzmnrq,
  author = {{iinventedlight}},
  title = {{Go modules and dependencies}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-03},
  url = {https://iinventedlight.com/library/notes/go-modules-basics/},
  note = {Permanent ID iil:note:e6mzmnrq. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/go-modules-basics.md.