The Package Clause

Every Go source file begins with a package clause. It is the first piece of actual code in the file, appearing before any import statements, function declarations, or type definitions. The clause is not optional; a file without one will not compile. Its role is to declare which package the file belongs to, and that single decision shapes everything from how the code is compiled to who can use it.

Understanding the Package Clause

Before a Go file can declare any imports, functions, or variables, it must declare which package it belongs to. The syntax is straightforward: the keyword package followed by a name.

package greeting

This statement must be the first non‑blank, non‑comment line in the file. The name you choose determines the package’s identity for the compiler and, in most cases, how other code will import and refer to it. Only one package clause is permitted per file, and every .go file in the same directory must use the same package name. That rule is strict: a directory containing package foo in one file and package bar in another will fail to compile.

The package clause exists because Go organizes code into compilation units. All files sharing a package name get compiled together. Functions, types, variables, and constants defined in one file of the package are directly visible to every other file in the same package — no imports or explicit visibility modifiers are needed. This design keeps closely related code cohesive while enforcing explicit boundaries between distinct packages.

Executable vs. Library Packages

The package clause carries a double duty: it tells the compiler how to treat the file at build time and whether the resulting code will be importable. Go recognizes exactly two categories of packages based on the name you write.

// main.go
package main
import "fmt"
func main() {
    fmt.Println("Hello, world.")
}

If the package name is main, the compiler produces an executable binary. The directory containing the main package must also include a main function — that function becomes the program’s entry point. When you run go build or go install, the output is a standalone binary you can run directly.

Any other package name creates a library package. Library packages are not runnable on their own; they are meant to be imported and used by other packages. A library package like morestrings can be imported by an executable (or by another library) and its exported identifiers become available through the package name.

Package Name, Directory, and Import Path

In Go, the physical layout of files on disk and the package name declared in each file are linked by a strict rule. All .go source files in a single directory must belong to the same package. You cannot split the implementation of one package across multiple directories, even if you write the same package declaration in each.

Consider this directory tree:

example/user/hello/
├── go.mod          (module example/user/hello)
├── hello.go        (package main)
└── morestrings/
    └── reverse.go  (package morestrings)

The import path for the morestrings package is formed by combining the module path with the subdirectory: example/user/hello/morestrings. The compiler does not require that the package name match the directory name, but the convention is to keep them identical. In the tree above, the directory is called morestrings and the package clause says package morestrings — that makes imports predictable and readable.

When you write an import statement, you reference the import path, not the package name. But inside the importing file, you use the package name to access its exported identifiers.

import "example/user/hello/morestrings"
func main() {
    // Use the package name, not the directory name
    fmt.Println(morestrings.ReverseRunes("!oG ,olleH"))
}

Common Pitfalls

A handful of mistakes with the package clause can cause confusing compiler errors or make code impossible to import. Many of them stem from incorrect assumptions about how Go maps directories to packages.

Another recurring mistake is attempting to split a single package across multiple directories. The language specification allows an implementation to require all source files of a package to inhabit the same directory, and the standard go toolchain enforces this. If your code feels too large for one directory, that is usually a signal to refactor into multiple smaller packages rather than to fight the tooling.

The main Package and Executable Entry Point

The main package is Go’s special signal for where execution begins. Any directory that contains package main and a function func main() is an executable command. There is no magic; the compiler simply looks for a main function inside a main package and wires it as the program’s entry point during linking.

A common beginner question is whether the main function must reside in a file named main.go. It does not. The file can be called anything, as long as it declares package main and contains func main(). This is the same visibility rule that applies to any package: identifiers defined in any file of the package are available across all files of that package. So you can spread helper functions, types, and variable declarations across multiple .go files in the same directory, and they will all be part of the single main package.

// cmd/main.go
package main
func main() {
    runApp()
}

// cmd/helpers.go
package main
import "fmt"
func runApp() {
    fmt.Println("Application started")
}

Both files above belong to the same main package because they share the same directory and use package main. Building the directory produces one binary.

The package Clause and the internal Visibility Rule

Go 1.5 introduced a convention that interacts directly with the package clause: the internal directory. When you create a subdirectory named internal, any package inside it can only be imported by code rooted at the parent of the internal directory.

For example:

mymodule/
├── go.mod
├── main.go            (package main)
├── pkg/
│   └── public.go      (package pkg)
└── internal/
    └── secrets/
        └── secrets.go  (package secrets)

Here, main.go and public.go can import mymodule/internal/secrets because they are within the mymodule tree. Any external module that tries to import mymodule/internal/secrets will receive a compile error. The package clause inside secrets.go remains package secrets and works exactly like any other library package; the restriction is enforced purely by the import path containing the word internal.

This mechanism gives you a way to enforce encapsulation without relying on unexported identifiers alone. You can break a large, complex package into multiple internal sub‑packages, each with its own package clause, while keeping them invisible to outside consumers. The package clause inside those internal packages stays normal — package validation, package logging, and so on — and you import them using full paths that include internal/.

Package Naming Conventions and Best Practices

Go encourages a minimalist approach to naming packages, and the package clause is where those names are declared. The official guidelines recommend:

• Lowercase, single‑word names. strings, http, json, time. Avoid underscores, mixedCaps, or multi‑word names whenever possible.
• The name should be the same as the last element of the import path. If the import path is example.com/user/hello/morestrings, the package name should be morestrings. This predictability makes Go code readable without constantly checking import declarations.
• Avoid generic names like util, common, or base. These tend to become dumping grounds for unrelated code. Instead, name the package after the concrete functionality it provides.
• Don’t repeat information the caller already knows. For example, a package that works with HTTP shouldn’t be httpclient.HTTPClient; it should be http.Client (package http, type Client). The package clause provides the context.

These conventions are not enforced by the compiler, but they are followed by virtually the entire Go ecosystem. When you write package myutil and place it in a directory called helpers/, you are setting up your users for confusion. Sticking to the norms keeps your code approachable.

How the Compiler Processes the Package Clause

When you run go build or go install, the compiler reads the package clause as the first step in determining what to compile and how to link it. It scans the source files in the target directory, checks that they all agree on the package name, and then treats them as a single compilation unit.

If the package name is main, the compiler flags the directory as an executable target. It then looks for a function named main with no parameters and no return value. If it finds one, it arranges for that function to be called when the resulting binary starts. If the directory is a library package (any name other than main), the compiler produces a compiled archive that will later be linked into an executable when that package is imported.

The package clause also seeds the namespace that importers will see. When another package writes import "example.com/mymodule/mypkg", the compiler locates mypkg’s source files, reads their package clause (which should say package mypkg), and binds that name into the importing file’s scope. If the package clause inside mypkg actually said package somethingelse, the importer would still need to reference somethingelse.Identifier, which would be surprising and error‑prone. That is why the convention of matching directory and package name is so important for sanity.

The package clause is the smallest but most structurally significant line in any Go source file. It draws the boundary between executable and reusable code, anchors the mapping between directories and import paths, and sets the stage for every visibility rule that follows. Getting it right from the start prevents entire categories of build errors and design headaches.

If you are writing a program that someone runs — a CLI tool, a server, a daemon — start with package main. If you are writing functionality meant to be imported by other programs or tests, choose a short, descriptive name and place it in a directory that shares that name. Keep all the files of a package together in one directory, and never try to import a main package. When you need to hide implementation details while splitting code across subdirectories, reach for the internal/ convention rather than bending the package‑directory rule.