Package Naming & internal/ Directories

Go package names and directory layout communicate intent before a reader opens a file.

Consistent short names plus internal/ directories keep public APIs honest and let the compiler enforce boundaries.

Summary

Package names should be lowercase, concise, and descriptive without redundant stutter.

Import paths carry the module prefix; package clauses name the compiled unit.

The special internal directory name restricts imports to ancestor directories inside the same module tree.

That combination reduces accidental coupling and makes refactors safer for library authors.

Recipe

Quick-reference recipe card - copy-paste ready.

// example.com/widget/internal/parser/parser.go
package parser // not package widgetparser
 
import "strings"
 
func Parse(raw string) (string, error) {
    return strings.TrimSpace(raw), nil
}

// example.com/widget/api/handler.go
package api
 
import "example.com/widget/internal/parser"
 
func Handle(raw string) (string, error) {
    return parser.Parse(raw)
}

When to reach for this:

• Naming a new package after its role (auth, store, parser), not the repo name.
• Placing implementation details under internal/ when external modules must not import them.
• Splitting cmd/ binaries from reusable packages in the same module.
• Reviewing imports in CI with go list or linters that flag stuttering paths.

Working Example

example.com/checkout/
  go.mod
  cmd/checkoutd/main.go
  checkout/          // domain types - import path ends in /checkout
    checkout.go
  internal/
    tax/
      tax.go
    payment/
      payment.go
  api/
    http.go

// checkout/checkout.go
package checkout
 
type Cart struct {
    Items []string
}

// internal/tax/tax.go
package tax
 
func Rate(region string) float64 {
    if region == "CA" {
        return 0.0725
    }
    return 0
}

// api/http.go
package api
 
import (
    "example.com/checkout/checkout"
    "example.com/checkout/internal/tax"
)
 
func Quote(c checkout.Cart, region string) float64 {
    return tax.Rate(region) * float64(len(c.Items))
}

What this demonstrates:

• Public domain types live in a top-level package with a clear name.
• internal/tax is callable from api/ because api is under the internal parent example.com/checkout.
• External modules may import checkout and api but not internal/tax.

Deep Dive

How It Works

• Package names appear in qualified identifiers (tax.Rate).

Short names read well at call sites because the import path already provides context.

• The compiler allows internal only when the importing package is beneath the directory that contains the internal folder.

For .../checkout/internal/tax, importers must live under .../checkout/.

• Multiple packages in one module each get their own subdirectory; you cannot mix package foo and package bar in the same folder.

Naming Rules at a Glance

internal/ vs pkg/

pkg/ does not hide symbols.

If you need hard guarantees, use internal/.

Go Notes

// Bad: stuttering at call site when import is renamed poorly
import checkoutinternal "example.com/checkout/internal/checkout"
 
// Good: internal detail with short package name
import "example.com/checkout/internal/tax"

// internal/ nested deeper still works - rule is per internal directory
// example.com/checkout/internal/payment/gateway/gateway.go
package gateway

Gotchas

• Import path vs package name mismatch confuses readers. Keep them aligned except for main and well-known stdlib cases.
• internal is path-based, not visibility-based. Lowercase identifiers are already package-private; internal/ blocks cross-module imports entirely.
• Moving code from public to internal/ is a breaking change for anyone who imported the old path.
• Generic folder names (utils) become junk drawers. Split by responsibility instead.
• Test packages package foo_test live beside foo and are a separate package for black-box tests.

Alternatives

• Multiple modules - Stronger release boundaries than internal/ when teams need separate semver.
• Go workspaces - Local development across modules without exposing private packages.
• Interface-only public packages - Small exported surface with implementation in unexported types (still not a substitute for internal/ across modules).

FAQs

Related

• Packages and Modules: Go's Unit of Distribution - Module paths and import paths
• Standard Project Layout for Services and Libraries - cmd, internal, pkg placement
• Import Cycles, Blank Imports & Dot Imports - Import patterns and cycles
• Packages & Modules Basics - Runnable naming and internal examples

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).