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