Skip to content
Tutorials Center
My learning

Topics

Lesson 96 of 147 ยท Modules and Packages

Project Layout and Multi-File Programs

Organize Go projects - multi-file packages, cmd and internal directories, build constraints, go:generate, go:embed, file name suffixes and go.work workspaces.

Sooner or later a single main.go stops being enough. Functions pile up, a second program appears (a command-line tool next to your server), you want to test pieces in isolation, and some code only makes sense on Linux. At that point you need conventions for where files go, how to split code across files and packages, and how to build for different platforms.

Go is relaxed about layout: the only hard rules are "one directory is one package" and "a module has one go.mod". Everything else is convention, and the conventions are small. This lesson shows the layouts that work for programs of different sizes, explains multi-file packages and file-name rules, and covers the special comments that drive the toolchain: //go:build constraints, //go:generate and //go:embed. It ends with go.work workspaces for developing several modules together.

Real projects need several files, which the browser editors cannot hold, so layouts and multi-file code appear as read-only blocks. Every runnable example uses the same machinery (embedding, build-constraint evaluation, code generation, directive parsing) inside one file.

Many files, one package

The first step in growing a program is to split main.go into several files in the same directory with the same package clause. Nothing else changes: no imports between those files, no export rules, no ordering. The files are simply concatenated by the compiler.

TEXT
todo/
โ”œโ”€โ”€ go.mod
โ”œโ”€โ”€ main.go        package main: wiring and flags
โ”œโ”€โ”€ store.go       package main: loading and saving
โ”œโ”€โ”€ commands.go    package main: add, list, done
โ””โ”€โ”€ commands_test.go
Go
// file: todo/main.go
package main

import (
	"fmt"
	"os"
)

func main() {
	tasks, err := load("tasks.json") // declared in store.go
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	run(os.Args[1:], tasks) // declared in commands.go
}

You run the program with go run . (the dot means "the package in this directory"), not go run main.go, which would compile only that one file and fail with "undefined: load". go build produces an executable named after the module's last path element, go install puts it into $GOPATH/bin, and go test runs every _test.go file.

How do you decide which declarations go to which file? Group by responsibility: one file for storage, one for the HTTP handlers, one for the domain types. A file of 300 to 600 lines about one subject is easy to navigate. The compiler doesn't care, but your teammates do.

If go run main.go says undefined: someFunction although the function exists in another file of the same package, that is the cause: you named only one file. Use go run .. The same command works for any layout in which main lives in the current directory.

Multiple packages in one module

When a part of the program has a clear boundary, such as a storage layer or a parser that could be used by more than one command, give it its own directory and package. It then gets its own namespace, its own tests and its own exported API. The import path is the module path plus the directory:

TEXT
todo/
โ”œโ”€โ”€ go.mod                      module example.com/todo
โ”œโ”€โ”€ main.go                     package main
โ””โ”€โ”€ task/
    โ”œโ”€โ”€ task.go                 package task
    โ””โ”€โ”€ store.go                package task
Go
// file: todo/main.go
package main

import (
	"fmt"

	"example.com/todo/task"
)

func main() {
	t := task.New("write lesson")
	fmt.Println(t)
}

The important thing to remember is that every package is a public boundary: what you export from task can be used by main and, if the module is published, by everyone. Keep it small, as discussed in Packages and Visibility.

Common layouts

There is no official standard layout, despite what some repositories claim. The Go team's own guidance is to start simple and add structure when you need it. These shapes cover most projects.

A small tool or a single-purpose program: everything in the root, package main, a handful of files.

TEXT
wordcount/
โ”œโ”€โ”€ go.mod
โ”œโ”€โ”€ main.go
โ”œโ”€โ”€ count.go
โ””โ”€โ”€ count_test.go

A library: the root directory is the public package, plus sub-packages for related pieces and an internal/ directory for details.

TEXT
greet/
โ”œโ”€โ”€ go.mod                 module github.com/you/greet
โ”œโ”€โ”€ greet.go               package greet   (import "github.com/you/greet")
โ”œโ”€โ”€ greet_test.go
โ”œโ”€โ”€ option.go
โ”œโ”€โ”€ internal/
โ”‚   โ””โ”€โ”€ plural/plural.go   private helpers
โ””โ”€โ”€ examples/
    โ””โ”€โ”€ basic/main.go      package main

An application with one or more commands: each executable gets a directory under cmd/, and the reusable code lives in internal/.

TEXT
shop/
โ”œโ”€โ”€ go.mod                       module example.com/shop
โ”œโ”€โ”€ cmd/
โ”‚   โ”œโ”€โ”€ shopd/main.go            the server
โ”‚   โ””โ”€โ”€ shopctl/main.go          an admin CLI
โ”œโ”€โ”€ internal/
โ”‚   โ”œโ”€โ”€ orders/                  domain logic
โ”‚   โ”œโ”€โ”€ catalog/
โ”‚   โ”œโ”€โ”€ httpapi/                 handlers, middleware
โ”‚   โ””โ”€โ”€ store/                   database access
โ”œโ”€โ”€ migrations/                  SQL files
โ”œโ”€โ”€ web/                         templates, static assets (can be embedded)
โ”œโ”€โ”€ go.sum
โ””โ”€โ”€ README.md

Building and running specific commands uses their package path:

Terminal
go build ./...                   # compile every package in the module (no output files for libraries)
go run ./cmd/shopd               # run the server
go build -o bin/shopctl ./cmd/shopctl
go test ./...                    # run all tests
go install ./cmd/...             # install every command

./... is Go's wildcard: "this directory and everything below it".

What each directory is for

  • cmd/<name>/ contains one package main per binary and is kept thin: parse flags, read configuration, construct the pieces and call into internal. A main function is hard to test, so put as little logic in it as possible. A good main is 20 to 50 lines.
  • internal/ holds the code that belongs to your application. The compiler guarantees nobody outside your module can import it (Packages and Visibility explains the rule), so you can refactor it freely. Most applications should put almost everything here.
  • pkg/ is a community habit for "code that is OK for others to import". It is not a Go feature, the tooling ignores it, and many respected projects don't use it. If you are writing an application, you don't need it. If you are writing a library, put public packages directly at the root or in named directories (greet/option).
  • Other directories (web, migrations, scripts, docs, testdata) are just directories. One of them has meaning for the tools: testdata, which go build ignores and which holds fixtures for tests.

Layout is a means, not a goal. A 400-line program with a cmd/, an internal/, three sub-packages and an api/ directory is harder to read than four files in one folder. Add a directory when you can name the responsibility it holds and when two other pieces of code need to share it.

File names that mean something

Besides _test.go, Go looks at the ending of a file name to decide whether to compile it:

  • *_test.go files belong to tests: go build ignores them, go test compiles them.
  • name_GOOS.go (for example socket_linux.go, path_windows.go) is built only on that operating system.
  • name_GOARCH.go (for example sum_arm64.go) is built only for that processor architecture.
  • name_GOOS_GOARCH.go (for example mem_linux_amd64.go) combines both.
  • Files whose names begin with _ or . are ignored completely, as is a directory named testdata.

Recognized values are lists such as linux, windows, darwin, freebsd, js, wasip1, and amd64, arm64, 386, wasm. A file called server_linux.go therefore compiles only on Linux, without any other annotation. Beware of accidents: config_prod.go is fine (prod is not a known OS), but util_linux.go that you meant as a Linux helper "utility" file really is Linux-only.

The usual pattern for platform-specific code is a shared file that declares the common API, plus one implementation per platform:

Go
// file: sysinfo/sysinfo.go  (all platforms)
package sysinfo

// Home returns the current user's home directory.
func Home() string { return home() }
Go
// file: sysinfo/home_unix.go
//go:build unix

package sysinfo

import "os"

func home() string { return os.Getenv("HOME") }
Go
// file: sysinfo/home_windows.go  (file name already says: windows only)
package sysinfo

import "os"

func home() string { return os.Getenv("USERPROFILE") }

Build constraints

When file name suffixes are not enough, put a build constraint at the very top of the file: a line comment //go:build followed by a boolean expression, which must be separated from the package line by a blank line. The expression uses &&, ||, ! and parentheses over tags.

Go
//go:build linux && (amd64 || arm64) && !cgo

package fast

The tags the toolchain knows about are the operating system (linux), the architecture (amd64), unix (true on all Unix-like systems), cgo, compiler names (gc, gccgo), release tags such as go1.22 (true when the toolchain is at least that version) and anything you pass with -tags.

A file with //go:build ignore is never part of a normal build (but you can still go run it: that's the convention for generator scripts). A custom tag is a feature switch:

Go
//go:build integration

package store_test // only compiled with: go test -tags integration ./...

The go/build/constraint package parses these expressions, which lets us evaluate one against different sets of tags:

Go Evaluating a build constraint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Eval takes a function that says whether each tag is set. The expression builds on Linux and macOS only when cgo is not enabled. Notice the error for the incomplete expression: a broken constraint is reported by the compiler as well, so a typo does not silently drop a file. (Old-style // +build lines were replaced by //go:build in Go 1.17; run gofmt and it will migrate them.)

To find out which tags are set on a machine, and where your build runs, use runtime.GOOS and runtime.GOARCH at run time. Build constraints are decided at compile time:

Go A file with a build constraint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

This file compiled because the server running it is Linux, so the constraint was satisfied. Compiling the same file for Windows (GOOS=windows go build) would produce "build constraints exclude all Go files". Cross-compiling is as simple as setting the two environment variables: GOOS=linux GOARCH=arm64 go build ./cmd/shopd. Go includes everything it needs, so no extra toolchain is required.

Generating code with go:generate

Some source code is better produced by a program than typed by hand: String() methods for enums, mocks, protocol-buffer bindings, database query code. A //go:generate comment records the command that creates a file, right next to the code that needs it:

Go
//go:generate stringer -type=Color

type Color int

const (
	Red Color = iota
	Green
	Blue
)

Running go generate ./... finds every such comment in the packages you name and executes its command from that package's directory. It is never run by go build or go test; you run it yourself (or in CI) and commit the generated file. Generated files should begin with the exact line // Code generated by <tool>; DO NOT EDIT. so that editors, linters and code review tools recognize them and skip them.

You can write generators yourself with text/template and format the result with go/format, which is the library behind gofmt:

Go A tiny code generator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The template produces valid but unevenly indented text; format.Source also checks that it parses, so a template mistake is reported at generation time with a line number, not as a puzzling error in your build. The printed result is exactly what gofmt would produce. In a real project you would write the bytes to color_gen.go with os.WriteFile.

The //go: comments are just comments that tools understand. The next program finds them in a source file in the same way go vet and go generate do, with go/parser:

Go Finding go: directives in a file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Directives start with //go: and no space after the slashes; // go:generate (with a space) is an ordinary comment and does nothing. That is why gofmt and vet treat them specially, and why they are not covered by doc comment formatting.

Embedding files with go:embed

Real programs need non-code files: HTML templates, SQL migrations, default configuration, static web assets. Shipping them next to the binary means they can be missing, mismatched or moved. The embed package (Go 1.16) compiles them into the executable. You place a //go:embed comment directly above a package-level variable of one of three types:

Go
package web

import "embed"

//go:embed templates/*.html
var templates embed.FS            // a read-only file system

//go:embed schema.sql
var schema string                 // one file as text

//go:embed logo.png
var logo []byte                   // one file as bytes

//go:embed static
var static embed.FS               // a whole directory tree

The rules are strict, which makes them safe:

  • Patterns are relative to the directory of the Go file and may not use .. or leave the module, so you cannot embed a file from outside your package.
  • Files whose names start with . or _ are skipped when a directory is embedded; use the prefix all: (//go:embed all:static) to include them.
  • The package embed must be imported (a blank import _ "embed" suffices for string and []byte).
  • The variable must be at package level, and the content is read-only.
  • The files must exist at build time, otherwise compilation fails.

An embed.FS implements io/fs.FS, so everything that reads file systems works with it: fs.ReadFile, fs.WalkDir, template.ParseFS and http.FS for serving static assets from a single binary.

The editors here compile one file called main.go, which is itself a file in the package directory, so the program can embed its own source code:

Go Embedding a file: the program reads itself

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Both variables hold the same bytes (one as string, one as []byte), embedded at compile time. If you delete main.go after compiling, the content is still in the binary. For embed.FS with several files, Files, Directories and Paths shows how to walk and read them.

Workspaces with go.work

Sometimes one change spans several modules: you are fixing a bug in a library and want to see the effect in the application that uses it, before you publish a new version. Without help you would add a temporary replace directive to go.mod and must remember to remove it. Workspaces (Go 1.18) solve this with a go.work file kept outside the modules, for example in a parent directory:

TEXT
work/
โ”œโ”€โ”€ go.work
โ”œโ”€โ”€ shop/        module example.com/shop  (the application)
โ””โ”€โ”€ greet/       module github.com/you/greet  (the library you are fixing)
Terminal
cd work
go work init ./shop ./greet
GO.WORK
go 1.24.0

use (
	./shop
	./greet
)

With this file present, the go command treats shop and greet as one build: shop imports github.com/you/greet and gets your local checkout, version number ignored. Nothing in either go.mod changes. go work use ./other adds a module and go work sync pushes workspace versions back into the modules' go.mod files.

Do not commit go.work for libraries and applications whose repository stands alone: it describes your machine's layout, not the project. Teams with a monorepo of several modules sometimes do commit it. You can ignore it for a build with GOWORK=off go build ./..., which is also what CI normally does, so a green local build can't hide a missing go.mod entry.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A package has main.go and helpers.go, both package main. go run main.go fails with undefined: helper. What is the fix?

    Files of one package need no imports between them, but go run main.go compiles only the file you name. go run . compiles every file in the directory.
  2. 2. Which file is compiled by go build on macOS?

    The darwin suffix selects macOS. Files with other operating-system suffixes are skipped, and _test.go files are compiled only by go test.
  3. 3. What is the purpose of the internal/ directory?

    The compiler enforces the internal rule, which makes internal/ the standard place for application code you don't want to export.
  4. 4. Which comment correctly generates code when you run go generate ./...?

    Directives start with //go: and no space. With a space it is an ordinary comment. go build and go test never run generators; go generate does.
  5. 5. What can //go:embed config.yaml above var cfg string do that reading the file at run time cannot?

    Embedded files are compiled into the binary. The file must exist at build time and must be inside the package directory tree.

Summary

  • A package is a directory; its files share one namespace with no imports between them. Run a multi-file program with go run ., build everything with go build ./..., test with go test ./....
  • Start flat. Add cmd/<name>/ for each executable (kept thin) and internal/ for application code. pkg/ is only a convention and usually unnecessary.
  • File names ending in _GOOS, _GOARCH or _test, and names starting with _ or ., change what is compiled. //go:build expressions add finer control, evaluated at compile time.
  • //go:generate records how to create generated files; go generate runs it on demand, and generated files carry a Code generated ... DO NOT EDIT. header.
  • //go:embed places files, directories or text into the binary as string, []byte or embed.FS; paths must be inside the package directory.
  • go.work lets you develop several modules together without editing go.mod; use GOWORK=off for a clean build.

Next: Working with Third-Party Packages