.MOD File Format

Introduction

A go.mod file defines a module in Go, the programming language created at Google. It is a UTF-8 text file with that exact name, kept in the root directory of the module. It gives the module’s path, the version of Go it needs, and the modules it depends on. The Go source files in the same tree make up the module’s packages.

The format is designed to be read by people and written by programs. The go command changes these files itself: go get upgrades or downgrades dependencies, go mod edit makes low-level edits, and commands that load the module graph can update the file when needed. Go programs can make the same changes with the golang.org/x/mod/modfile package.

A go.mod file is required for the main module, which is the module in which the go command is invoked, and for any replacement module given by a local file path. A module without one may still be required as a dependency, or used as a replacement given by a module path and version.

The .mod extension

The .mod extension is shared with other formats, among them the tracker music module, which has nothing to do with Go. Every other format that uses the extension is listed under Also used for, below.

The file viewer on this site tells them apart by content, not by name. It shows a .mod file as a Go module file only when the file is text that opens with a module line, after any blank lines and comments. Other .mod files go to the other readers, such as the one for tracker modules. The viewer shows a Go module file as coloured text.

Structure

The file is line-oriented. Each line holds a single directive: a keyword followed by its arguments. Comments start with // and run to the end of the line.

module example.com/my/thing

go 1.23.0

require example.com/other/thing v1.0.2
require example.com/new/thing/v2 v2.3.4
exclude example.com/old/thing v1.2.3
replace example.com/bad/thing v1.4.5 => example.com/good/thing v1.4.5
retract [v1.9.0, v1.9.5]

The leading keyword can be factored out of adjacent lines to make a block, as with Go imports.

require (
    example.com/new/thing/v2 v2.3.4
    example.com/old/thing v1.2.3
)

These are all the directives.

Not yet covered

This page is a partial reference. It gives the layout of the file and the purpose of every directive. It does not yet give the lexical elements in full, the rules for module paths and versions, the grammar, the detailed rules and examples for each directive, or how the go command updates the file automatically. All of these are in the Go Modules Reference.

Related files

• go.sum is a text file that may sit beside go.mod. It holds cryptographic hashes of the module’s direct and indirect dependencies, which the go command checks when it downloads them. See go.sum on the Go reference pages.
• go.work is a UTF-8 text file that defines a workspace: a collection of modules on disk that are used together as main modules. It is line-oriented like go.mod, with the directives go, toolchain, godebug, use and replace. See Workspaces on the Go reference pages.

Also used for

• Multichannel module (xCHN, xxCH) – 31 samples and any channel count other than 4, marked 6CHN, 8CHN, 16CH and so on.
• ProTracker 3.6 module (IFF) – An IFF wrapper around a module, with version, song information and a comment.
• ProTracker module (M.K.) – 31 samples and 4 channels, marked M.K. at offset 1080: the standard Amiga module.
• Soundtracker module (15 samples) – The first modules, 1987 to 1989: 15 samples, a 600-byte header and no signature.
• StarTrekker 8-channel module (FLT8) – StarTrekker’s 8 channels, each pattern stored as two 4-channel patterns.
• Tracker module – Amiga tracker songs in four layouts: samples, an order list and patterns of notes.

Links