Go Folder Structure: cmd, internal and pkg Explained
November 11, 2026 · 10 min read
Go Folder Structure: How to Lay Out a Go Project, From go.dev
A good go folder structure starts small: one go.mod file and one package at the repository root. You add an internal/ directory when you need private helper packages, and a cmd/ directory when the repository builds several programs. That's the path the Go team documents on go.dev, and this guide follows it step by step.
What Is the Recommended Go Folder Structure?
The Go team's answer lives in Organizing a Go module on go.dev. Its simplest case is a single package: a go.mod file, a source file and a test file, all in the repository root.
modname/
├── go.mod
├── modname.go
└── modname_test.go
You create the go.mod file with go mod init and the module path, which is often the repository's location, such as a GitHub path:
mkdir modname && cd modname
go mod init github.com/someuser/modname
The command writes a two-line file. The module line sets the import path prefix for every package in the module. The go line is the minimum Go version the module needs. Since Go 1.26, go mod init writes the previous minor release rather than your exact toolchain. Go 1.27.x writes go 1.26.0, as below, while toolchains before Go 1.26 write their own version.
module github.com/someuser/modname
go 1.26.0
Three rules shape everything that follows. Each directory holds exactly one package, and every non-test .go file in it declares the same package name. A package's import path is the module path plus its folder, so auth/ becomes github.com/someuser/modname/auth. File names are your choice: go.dev points out that calling the entry file main.go is only a convention.
Folder names follow the package names inside them. Effective Go, on go.dev, asks for short, lowercase, single-word package names with no underscores or mixedCaps. It also describes the convention that a package's name is the base name of its directory. So prefer internal/userstore/ over internal/user_store/ or internal/UserStore/.
Is There an Official Standard Go Project Layout?
No single layout is mandated by the toolchain, but go.dev's page is the official guidance. The popular golang-standards/project-layout repository is not. Its own README says it's "NOT an official standard defined by the core Go dev team", links to the go.dev page, and calls its layout overkill for a simple project.
The repository's name still causes confusion, and searches for a golang project structure often land on it first. In April 2021, Russ Cox of the Go team opened issue #117, titled "this is not a standard Go project layout". He noted that the vast majority of Go packages don't put importable code in a pkg/ subdirectory. So when someone says you're "not following the standard layout", ask which standard they mean.
Growing a Go Project Structure From One Package to cmd/
The go.dev guide works like a ladder. You climb a rung only when the code asks for it, which keeps a small Go project structure small.
Rung 1: more files, same package. A growing package splits into auth.go, hash.go and their tests, all in the root directory and all declaring package modname. No new folders yet. A small command-line tool has the same flat shape, with main.go and every other file declaring package main:
modname/
├── go.mod
├── main.go
├── client.go
├── auth.go
└── auth_test.go
Anyone can install that tool with go install github.com/someuser/modname@latest, because the module root is the program.
Rung 2: supporting packages in internal/. When a chunk of code deserves its own package, go.dev recommends putting it under internal/ first:
modname/
├── go.mod
├── modname.go
├── modname_test.go
└── internal/
├── auth/
│ ├── auth.go
│ └── auth_test.go
└── hash/
├── hash.go
└── hash_test.go
The root package imports it as github.com/someuser/modname/internal/auth. Other modules can't import it at all, so you're free to rename and refactor.
Rung 3: several programs. Each program gets its own directory whose files declare package main. go.dev calls a cmd/ directory for them a common convention. It's most useful when the repository also exports packages, like this one.
modname/
├── go.mod
├── modname.go
├── auth/
│ └── auth.go
├── internal/
│ └── trace/
│ └── trace.go
└── cmd/
├── prog1/
│ └── main.go
└── prog2/
└── main.go
Users install one program with its full path, and the go command names the binary after the last path element (prog1):
go install github.com/someuser/modname/cmd/prog1@latest
What Does internal/ Enforce That pkg/ Doesn't?
internal/ is the one layout rule the go command checks. Per the cmd/go documentation on internal packages, code in or below a directory named internal can only be imported by code inside the tree rooted at that directory's parent. Break the rule and the build fails with use of internal package ... not allowed.
The directory doesn't have to sit at the root. In the docs' example, foo/internal/baz is importable from foo and foo/bar, but not from crash/bang. That lets one part of a large module keep helpers private even from its neighbors.
pkg/ has no meaning to the toolchain. It's a folder name, and go.dev's layout guide never mentions it. Here's how the special and conventional names compare:
| Name | What the go command does with it |
|---|---|
internal/ | Restricts imports to code under the parent directory |
testdata/ | Ignores it, so test fixtures can live there |
vendor/ | Holds vendored dependencies; skipped by ./... patterns |
Names starting with _ or . | Ignores them when matching packages |
cmd/, pkg/, api/, configs/ | Nothing special; pure convention |
So should you use pkg/ in an application? Usually not. We prefer internal/ by default and moving a package up to the module root, next to go.mod, only when another project really needs to import it. Once a package is public, its API is a promise you have to keep.
How Should You Structure a Go API or Web Service?
A server rarely exports packages, so go.dev recommends keeping its logic in internal/ and its binaries in cmd/. A shop backend with an HTTP API and a background worker might look like this:
shop/
├── go.mod
├── go.sum
├── cmd/
│ ├── api-server/
│ │ └── main.go
│ └── worker/
│ └── main.go
├── internal/
│ ├── order/
│ ├── payment/
│ └── platform/
│ └── postgres/
├── migrations/
├── web/
├── Dockerfile
└── README.md
Keep each main.go thin. It reads configuration, wires dependencies together and starts the server. The real work happens in internal/.
package main
import (
"log"
"net/http"
"github.com/acme/shop/internal/order"
)
func main() {
mux := http.NewServeMux()
mux.Handle("/orders", order.NewHandler())
log.Fatal(http.ListenAndServe(":8080", mux))
}
Many Go developers group internal packages by feature (order, payment) rather than by layer (models, controllers). That keeps related code in one place and avoids a package that everything imports. Hexagonal or domain-driven layouts are an option for large services, not a starting point.
One limitation to accept: go.dev deliberately covers only the Go code. Where migrations/, web/, Dockerfiles and deployment scripts go is up to your team, so pick names and write them down.
Where Do Tests and Test Data Go in a Go Project?
Tests sit right beside the code they test, in files ending in _test.go. There's no separate tests/ tree to mirror. A test file can declare the same package (package order) to reach unexported code, or package order_test to test only the exported API like an outside caller would. If you're coming from Python, our Python project structure guide shows the top-level tests/ layout for comparison.
Fixtures go in a testdata/ directory inside the package:
internal/order/
├── order.go
├── order_test.go
└── testdata/
└── order.json
The go tool ignores testdata/, and go test runs each package's tests from that package's directory. A relative path therefore works:
data, err := os.ReadFile("testdata/order.json")
That line opens internal/order/testdata/order.json during go test ./.... Slow end-to-end suites sometimes get their own top-level directory, such as e2e/. That's a team convention, not something the go command knows about.
One Module or Several? go.mod, go.work and Repo Boundaries
Start with one go.mod at the repository root. It covers every package below it, and go test ./... reaches all of them. For server repositories, go.dev suggests splitting packages off into a separate module once they become useful to other projects.
When you do run several modules side by side, a go.work file lets you build them together locally. It arrived in Go 1.18:
go work init ./shop ./billing
Workspaces don't relax the internal/ rule, because that rule compares import paths. A module at github.com/acme/billing can't import github.com/acme/shop/internal/order, workspace or not. Shared code belongs in a module that exports it.
Two smaller boundary rules are worth knowing. A subdirectory with its own go.mod is a separate module, so ./... in the parent skips it. And from v2 onward, the module path must end in a major version suffix such as /v2.
Documenting the Layout in Your README
Newcomers to a repository look for the layout first. A short annotated tree of your golang folder structure in README.md answers most of their questions.
shop/
├── cmd/ # one folder per binary (api-server, worker)
├── internal/ # all application code; not importable by other modules
├── migrations/ # SQL migrations, applied in order
└── web/ # templates and static assets
Put the tree in a fenced block tagged text, which our Markdown code block guide covers in detail. For the rest of the file, see the README Markdown guide. Longer explanations belong in a docs/ folder, and writing documentation in Markdown shows how to structure it.
You don't have to align the ├── and └── connectors yourself. The directory tree generator draws them from an indented list or a list of paths. You can also pick or drop a folder, and it reads the file paths in your browser without uploading them. It outputs box-drawing, ASCII, a Markdown list or tree-style text, but it only draws the layout; it doesn't create folders or run go mod init. In a terminal, the Linux tree command prints an existing folder's layout.
To check how the README reads, paste it into the online Markdown editor. It's free, needs no account, and shows a live preview on the right as you type.
A clean go folder structure grows in steps: one package at the root, helpers in internal/, programs in cmd/, and tests with their testdata/ beside the code. Only internal/ and testdata/ mean something to the go command, so everything else is a choice you should document. Sketch your tree with the directory tree generator, then preview the README in the editor before you commit.