Master Go Project Layout: Best Practices for Organizing Your Go Modules

New Go developers often wonder how to organize their Go projects; while there is no single standard, the Go official documentation offers a recommended layout. This guide walks through the official guidance and demonstrates practical directory structures for various Go project types.

Basic Go package

For the simplest package, place all files at the project root:

project-root-directory/
  go.mod
  modname.go
  modname_test.go

The module line in go.mod should match the repository URL, e.g. module github.com/someuser/modname. The package is declared as package modname and can be imported with import "github.com/someuser/modname". Multiple files can belong to the same package, each declaring package modname.

NOTE: Go prefers hyphen‑separated directory names (e.g., project-root-directory ) and concatenated file names (e.g., modname.go ) rather than snake_case.

Executable Go program

A minimal program contains a single main function, but larger programs can split code across files:

project-root-directory/
  go.mod
  auth.go
  auth_test.go
  client.go
  main.go

The main.go file holds the main function, though any xxx.go file can contain it. When the program spans multiple files, run it with go run . and install with go install github.com/someuser/modname@latest.

More complex Go program

For larger projects, use an internal directory for private packages and organize code into sub‑directories:

project-root-directory/
  internal/
    auth/
      auth.go
      auth_test.go
    hash/
      hash.go
      hash_test.go
  go.mod
  modname.go
  modname_test.go

The internal packages cannot be imported by external modules, providing a built‑in encapsulation mechanism.

Project with multiple packages

A module can contain many packages, each in its own sub‑directory. Example layout:

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth/
    auth.go
    auth_test.go
    token/
      token.go
      token_test.go
  hash/
    hash.go
  internal/
    trace/
      trace.go

Import the root package with import "github.com/someuser/modname" and sub‑packages with their full paths, e.g., import "github.com/someuser/modname/auth". The internal/trace package remains private.

Multiple executable programs

When a repository contains several commands, place each under cmd/:

project-root-directory/
  go.mod
  internal/ ...
  cmd/
    prog1/
      main.go
    prog2/
      main.go

Install each with go install github.com/someuser/modname/cmd/prog1@latest and go install github.com/someuser/modname/cmd/prog2@latest.

Server project

Typical Go server projects follow a similar layout, with shared internal packages and command‑specific binaries under cmd/:

project-root-directory/
  go.mod
  internal/
    auth/ ...
    metrics/ ...
    model/ ...
  cmd/
    api-server/
      main.go
    metrics-analyzer/
      main.go

This structure is common in large Go services such as Kubernetes.

Summary

We have covered the official Go module layout recommendations, illustrating how to organize basic packages, executable programs, complex projects, multiple commands, and server applications. The article also showed how to install Go programs using go install.

Organizing a Go module: https://go.dev/doc/modules/layout

Standard Go Project Layout: https://github.com/golang-standards/project-layout

Tutorial: Create a Go module: https://go.dev/doc/tutorial/create-module

Managing module source: https://go.dev/doc/modules/managing-source

Internal Directories: https://pkg.go.dev/cmd/go#hdr-Internal_Directories