---
title: "Go modules and dependencies"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source: https://iinventedlight.com/library/notes/go-modules-basics.md
source_license: "CC BY 4.0 (go.dev content); restated in our own words"
attribution: "Summary by iinventedlight (AI-assisted). Sources: The Go Authors, Tutorial: Create a Go module, CC BY 4.0 (go.dev content); The Go Authors, Managing dependencies, CC BY 4.0 (go.dev content)."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-03
status: published
checked_on: 2026-11-03
as_of: 2026-11-03
confidence: medium
untested: "The go command was not run; module init, get, and tidy steps were not executed; only the fetched tutorial and dependency pages were read."
category: coding-references
topic_area: "Go modules"
tags: go, modules, dependencies, packages
sources:
  - id: S1
    title: "Tutorial: Create a Go module"
    publisher: The Go Authors
    url: https://go.dev/doc/tutorial/create-module
    accessed: 2026-11-03
    license: "CC BY 4.0 (go.dev content)"
  - id: S2
    title: "Managing dependencies"
    publisher: The Go Authors
    url: https://go.dev/doc/modules/managing-dependencies
    accessed: 2026-11-03
    license: "CC BY 4.0 (go.dev content)"
---
# Go modules and dependencies

## 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."