Golang Packages and Imports: Exported Names, Multiple Files

Every Go file belongs to a package, declared on its first line. Code in one package uses another by importing it and prefixing names with the package name. Only names that start with a capital letter can be used from outside the package.

package main

import (
	"fmt"
	"math"
	"strings"
)

func main() {
	fmt.Println(strings.Repeat("go", 3))
	fmt.Println(math.Sqrt(2))
	fmt.Println(strings.ToUpper("exported names start with a capital"))
}

fmt, math and strings are standard library packages. They ship with Go, so "adding" one means writing its name in the import block. Nothing is downloaded. fmt.Println, math.Sqrt and strings.Repeat are capitalized because they are exported.

The Package Clause

The first non-comment line of every .go file is package name. All files in one directory must use the same name, and together they form one package. A directory with two different package names does not compile:

found packages greeting (b.go) and greet (greet.go) in /home/ana/shop/greet

(The one exception is test files, which may use package name_test.)

package main is special: it produces an executable, and the program starts at its func main(). Every other package is a library meant to be imported.

By convention the package name matches the last element of the directory path: code in shop/greet is package greet. Package names are short, lowercase, single words, with no underscores or mixed caps: strconv, httptest, greet, not string_utils or greetHelpers.

Importing Packages

An import path is a string. For the standard library it is the package's path under Go's source tree; for everything else it starts with a module path:

import (
	"fmt"           // standard library
	"net/http"      // standard library, nested path
	"math/rand/v2"  // standard library, version 2 of math/rand

	"github.com/google/uuid"   // another module (needs go get)
	"example.com/shop/greet"   // a package in your own module
)

The path is where the package lives; the name is what you type in code. For net/http the name is http, for math/rand/v2 it is rand. You write http.Get, never net/http.Get.

gofmt and goimports sort the block and conventionally separate standard library imports from the rest with a blank line.

Unused imports are a compile error:

./main.go:5:2: "os" imported and not used

Editors with Go support run goimports on save, which adds missing standard imports and removes unused ones for you.

Exported vs Unexported Names

Visibility in Go is decided by one rule: if a name starts with an uppercase letter, it is exported. That applies to functions, types, variables, constants, struct fields and methods. There are no public, private or protected keywords.

Trying to use an unexported name from another package gives an undefined error:

./main.go:11:20: undefined: greet.prefix

The rule matters even inside a single file, because other packages inspect your types. encoding/json can only see exported fields:

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	Name  string
	Email string
	token string // unexported: invisible to encoding/json
}

func main() {
	u := User{Name: "Ana", Email: "ana@example.com", token: "secret"}
	data, err := json.Marshal(u)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println(string(data))
}

token is left out of the JSON, silently. That is a feature when the field is private data and a surprise when you forgot to capitalize a field you wanted.

Splitting a Package Across Files

A package can span as many files as you like. Every file in the directory with the same package line sees every name declared in the others, exported or not, without importing anything:

shop/
├── go.mod        (module example.com/shop)
├── main.go
└── math.go

// main.go
package main

import "fmt"

func main() {
	fmt.Println(total(2, 3))
}

// math.go
package main

func total(a, b int) int { return a + b }

main.go calls total directly. There is no #include and no import between files of the same package.

The "undefined" error from go run main.go

This is the most searched package problem in Go, and it has one cause. Running only the file that contains main compiles only that file:

go run main.go

# command-line-arguments
./main.go:6:14: undefined: total

command-line-arguments is the name Go gives to a package built from a list of files, and math.go is not in that list. Run the whole package instead:

go run .

5

The same applies to go build main.go. Use go run . and go build (or go build ./cmd/app) and the problem never appears. If it persists with go run ., check that both files say package main and that neither has a build constraint (//go:build) or a _test.go suffix excluding it.

Your Own Packages

A subdirectory of your module is a separate package. Import it with the module path from go.mod plus the directory:

shop/
├── go.mod          (module example.com/shop)
├── main.go
└── greet/
    └── greet.go

// greet/greet.go
package greet

const prefix = "Hi, "

// Hello returns a greeting for name.
func Hello(name string) string {
	return prefix + name
}

// main.go
package main

import (
	"fmt"

	"example.com/shop/greet"
)

func main() {
	fmt.Println(greet.Hello("Ana"))
}

Hi, Ana

Two things trip people up here. The import is the module path plus directory, not a relative path: "./greet" does not work in module mode. And prefix stays hidden from main because it is lowercase; only Hello is part of the package's API.

Internal Packages

A directory named internal restricts who can import what is inside it. Code in shop/internal/store can be imported by any package rooted at shop/, and by nothing outside it. Another module that tries gets:

use of internal package example.com/shop/internal/store not allowed

Use internal/ for code you want to share between your own packages without promising it to the rest of the world. You can change its API freely, since no outside code can depend on it.

Import Aliases

Give an import a different local name by writing the name before the path. The usual reason is two packages with the same name:

package main

import (
	crand "crypto/rand"
	"fmt"
	mrand "math/rand/v2"
)

func main() {
	buf := make([]byte, 4)
	if _, err := crand.Read(buf); err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println("crypto bytes:", len(buf))

	r := mrand.New(mrand.NewPCG(1, 2))
	fmt.Println("seeded rolls:", r.IntN(6)+1, r.IntN(6)+1, r.IntN(6)+1)
}

Both packages are called rand, so at least one needs an alias. Use aliases for conflicts and for names that are unclear; do not rename packages just to shorten them, since readers know strconv and not your sc.

Blank and Dot Imports

Blank import (_). Imports a package only for its side effects: its package variables and init functions run, but you use none of its names. Database drivers and image decoders register themselves this way:

import (
	"database/sql"

	_ "github.com/lib/pq" // registers the "postgres" driver with database/sql
)

Without the _, the import would be an unused-import error.

Dot import (.). Puts the package's exported names directly into your file's scope, so you write Println instead of fmt.Println. It hides where names come from and is discouraged outside a few test helper patterns.

Import Cycles

Go does not allow two packages to import each other, directly or through a chain:

package example.com/shop
	imports example.com/shop/greet from main.go
	imports example.com/shop/other from c.go
	imports example.com/shop/greet from o.go: import cycle not allowed

The error lists the chain. Two fixes cover almost every case:

1. Move the code both packages need into a third, lower-level package that both import.
2. If package A only needs to call something in B, define a small interface in A and let B's type satisfy it. A no longer imports B.

A cycle usually means the package boundaries are drawn around layers of code that actually belong together, so it is also a signal to reconsider the split.

Common Mistakes

• Running a single file. go run main.go in a multi-file package: use go run ..
• Relative imports. import "./utils" fails in module mode. Use "example.com/yourmodule/utils".
• Lowercase names you meant to export. A function, field or method that other packages need must start with a capital letter.
• Package name that does not match the directory. Legal, but confusing: the import path says utils and the code says helpers.X. Keep them the same.
• Catch-all package names. util, common and misc say nothing about their contents and tend to grow into import-cycle magnets. Name packages after what they provide: money, auth, slug.