Fundamentals

Project Structure

Learn how modules, packages, and files relate, and how Go commands decide what to build.

What you will learn

This lesson explains the three levels that organise every Go project, which are modules, packages, and files, and how Go commands choose what to build. You will learn what ./... means, where go build puts its output, and why packages cannot import each other in a circle.

Three levels

LevelWhat it isHow you recognise it
ModuleOne versioned project with its own dependenciesA folder containing go.mod
PackageA set of files compiled togetherOne directory of .go files with the same package line
FileA single source fileA .go file

The relationship is simple: a module contains packages, and a package contains files. The golden rule is one directory, one package. Every .go file in a directory declares the same package name, and a subdirectory is a different package.

Take this project:

myapp/
├── go.mod
├── main.go
├── cmd/
│   └── tool/
│       └── main.go
└── internal/
    └── report/
        ├── report.go
        └── format.go

It is one module with three packages: the root package (main.go), cmd/tool (also a main package), and internal/report (which has two files). Go does not care about the nesting depth. Each directory simply becomes one package.

You first met modules in the Getting Started section. Here is the short version: go mod init <path> creates go.mod, which records the module path and its dependencies.

The module path

The module path is the prefix of every import path inside your project. If go.mod says module example.com/myapp, then the package in internal/report is imported as example.com/myapp/internal/report.

If you plan to publish the project, use its real repository path from the start, for example github.com/yourname/myapp. Renaming later means editing every import.

How commands pick a target

Most Go commands work on packages, not on single files. You tell them which packages with a pattern:

PatternMeaning
.The package in the current directory
./cmd/toolThe package in that specific directory
./...The current directory and every package below it

Some examples:

Terminal
go run .              # build and run the package in this folder
go run ./cmd/tool     # build and run a different main package
go build ./...        # compile everything, to check it all builds
go test ./...         # run the tests in every package

You can also run go run main.go to compile a single file, but that ignores the rest of the package, as the previous lesson showed. Prefer ..

Where go build puts its output

go build writes an executable only when the package is a main package. The file is named after the last part of the module path, or the folder you pointed at:

Terminal
go build .             # creates ./myapp   (myapp.exe on Windows)
go build ./cmd/tool    # creates ./tool
go build -o bin/server .   # creates bin/server, a name and place you choose

If you build a package that is not main, Go compiles it to check for errors, but writes no file. go build ./... behaves this way for packages that are libraries.

If you run a Go command outside a module, you may see:

go: go.mod file not found in current directory or any parent directory

Change into your project folder, or run go mod init first.

Visibility follows packages

Because each directory is a package, directories also set visibility boundaries. A lowercase name is visible only inside its own package. So code in cmd/tool cannot call a lowercase function in internal/report, even though both are in one module. It can only call exported (uppercase) names.

The internal directory adds one more rule, enforced by the compiler: a package under internal/ can only be imported by code inside the parent of that internal folder. In the project above, anything in myapp can import internal/report, and no other module can.

Import cycles

Packages form a graph of imports, and that graph must not contain a loop. If package a imports b, then b cannot import a, directly or through other packages:

package example.com/myapp/a
    imports example.com/myapp/b
    imports example.com/myapp/a: import cycle not allowed

A cycle usually means two packages are too tangled and one responsibility belongs somewhere else. The usual fix is to move the shared piece into a third package that both of them import.

Common mistakes

  • Putting two package names in one directory. Go rejects it.
  • Using go run main.go and wondering why other files are missing. Use go run ..
  • Creating a package for every file. A package is a unit of related code, not one file.
  • Importing a package by its folder path alone. The import path starts with the module path.

Practice

A module contains the folders cmd/tool and internal/report. How many packages are involved? Can cmd/tool call an unexported function that lives in internal/report? Which commands would you run to build only the tool, and to test everything?

Summary

A module contains packages and a package contains files, with one directory per package. The module path becomes the prefix of every import path, and it only needs to be a real address when others will download the code. Go commands act on packages through patterns: . for the current one and ./... for everything below. Directories are also visibility boundaries, internal restricts who may import a package, and import cycles are not allowed.

Official reference: How to write Go code.

Ready to wrap up?

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

Copyright © 2026