Fundamentals

Project Layout

Grow a Go project's folder layout in stages, and learn when cmd, internal, and pkg directories actually help.

What you will learn

Go does not force a folder layout on you, and that freedom makes beginners nervous. This lesson shows how a project grows in stages, so you always know the smallest layout that fits, and explains what the common folders cmd, internal, pkg, and api are for, and when to leave them out.

There is no official layout

The Go toolchain only requires a go.mod file and directories that contain packages. Everything else is convention. Large open-source projects have organised themselves in many different ways, and copying a big layout into a tiny project is a common beginner mistake. It adds folders, imports, and indirection before they solve any problem.

The rule to follow is simple: start flat, split when it hurts.

Stage 1: one file

For a script or a small tool, this is enough:

hello/
├── go.mod
└── main.go

Run it with go run .. There is nothing wrong with a project that stays like this.

Stage 2: several files, one package

When main.go grows past a few hundred lines, split it by topic but keep a single package:

tasker/
├── go.mod
├── main.go        # starts the program
├── tasks.go       # task type and operations
└── storage.go     # loading and saving

All three files declare package main, so they share names with no imports. This is the cheapest way to get readable files.

Stage 3: your own packages

Create a new package when a group of code has a clear responsibility and a name that describes it:

tasker/
├── go.mod
├── main.go
└── task/
    ├── task.go
    └── storage.go

main.go now imports example.com/tasker/task. A good signal that you need a package is when you can describe it in one short phrase, such as "task storage", and you want a boundary around it. Names should be short and lowercase: task, storage, auth. Avoid vague names like utils, common, or helpers, which turn into dumping grounds.

Stage 4: commands and internal code

When the project has more than one executable, or when most of its code should not be importable by others, use cmd and internal:

myapp/
├── go.mod
├── cmd/
│   ├── api/
│   │   └── main.go
│   └── worker/
│       └── main.go
└── internal/
    ├── app/
    │   └── app.go
    └── storage/
        └── storage.go

Here is a small working version:

cmd/api/main.go
package main

import (
    "fmt"

    "myapp/internal/app"
)

func main() {
    fmt.Println(app.Start())
}
internal/app/app.go
package app

func Start() string {
    return "app started"
}
go.mod
module myapp

go 1.26

Run it from the module root:

Terminal
go run ./cmd/api
app started

What each folder is for

/cmd
Holds one subfolder for each executable the repository produces, such as cmd/api and cmd/worker. Each subfolder contains a small package main that wires things together and starts the program. Keep the real logic out of it, so it can be reused and tested elsewhere. Use cmd when you have more than one program, or when you want main to be a thin starter.
/internal
Holds code that only your own module may import. The compiler enforces this, so you can change it freely without breaking outside users. Most application code (services, handlers, storage, business rules) belongs here, because most applications are not libraries.
/pkg
A convention, not a Go rule. It signals "packages meant for other projects to import". Many projects skip it entirely and put public packages at the top level. Use it only if you intentionally publish reusable packages next to a lot of other files and want to make that obvious. Never put business logic here just to have something in it.
/api
A convention for API definitions, such as OpenAPI files or protobuf schemas. It holds contracts, not handler code. Create it only when you actually have such files.
/go.mod
Required, at the root of the module. It names the module and lists dependencies. All the folders above live below it.

Signs a layout is too big

  • Folders that each contain a single file with a single function.
  • Every package imports every other package.
  • You spend more time deciding where code goes than writing it.
  • A utils or common package keeps growing.

The fix is to merge folders back together. Package boundaries should reflect real responsibilities, not a desire to look organised.

Common mistakes

  • Copying a template layout on day one. Start flat and let the structure appear when you need it.
  • Splitting by technical kind (models/, controllers/, helpers/) instead of by responsibility. Prefer packages named for what they do, like billing or auth.
  • Using pkg as a default. It carries no special meaning to Go.
  • Creating import cycles by splitting too aggressively. If two packages need each other, they probably belong together.

Practice

You are building three things: (a) a 40-line program that renames files, (b) a web API plus a separate background worker that share storage code, and (c) a small library other people will import. Choose a layout for each.

Summary

Go has no mandated project layout, so start with one file, then several files in one package, then your own packages, and only then cmd and internal. Use cmd for multiple executables, internal for code that only your module should import, and treat pkg and api as optional conventions. If a layout makes you spend more time arranging than coding, it is too big.

Official reference: Organizing a Go module.

Ready to wrap up?

Mark this complete when you can explain the main idea and finish the practice task.

Copyright © 2026