Understanding Golang Packages And Modules

Packages

Packages are basically folders/directories that contains a bunch of go source code files. These files shares the same package name and can access each other's private (unexported) variables and functions.

(do they need to be in the same folder tho? What if they share the same package name but are in different folders?)

Every Go file begins with a package declaration. This isn't just boilerplate but the core organizational principle of the language. Think of a package as a workspace in a workshop. When you sit down to code, you have all your tools like keyboard, mouse, charger, laptop readily available in one area, but if you wanna eat something, you either go to kitchen or you bring your food to your table. In Go, "bringing your food to the work table" is importing another package.

When you write package main at the top of a file, you're declaring "this file belongs to the main package." When you write package httputil, you're saying "this file belongs to the httputil package." Every file in the same directory must share the same package name (with one exception we'll discuss later). This isn't a suggestion, it's enforced by the compiler.

Example:

package mathutils
 
func Add(a int, b int) int {
    return a + b
}

Here, mathutils is the package name it groups related mathematical functions.

Why do we need packages tho?

Few reasons:

• You don't want all your code in the same file. For large codebases, development and debugging quickly turns into a nightmare. Packages let you split code by responsibility, database logic in one place, HTTP handlers in another, business rules somewhere else. This mirrors how you think about the problem, making the codebase easier to navigate and reason about.

• Packages helps in maintaining code reusability across the codebase. Instead of copying the same utility functions into every project, you write them once in a package and import them wherever needed. The standard library itself is built this way, fmt for formatting, net/http for web servers. Imagine starting a project without these packages.

• Packages control visibility through naming. This is also called Encapsulation. Capitalize a function or type to export it, keep it lowercase to hide it. This forces intentional API design. Consumers see only what you want them to see, while you're free to refactor internals without breaking external code.

• Go compiles packages independently and caches the results. If you're working on a large project and modify one file, only that package and its dependents rebuild. Everything else skips compilation, turning what could be minutes into seconds.

• Imports create an explicit dependency graph. You can see at a glance what your code relies on, swap implementations by changing imports, and version your packages as modules for distribution. This clarity makes collaboration and dependency management significantly easier.

The Two Types of Packages

Command Packages

This is the main entry point for any golang project. These source files use package main . These are programs you run, executables that produce a binary when compiled.

• A command package must contain func main() that serves as the entry point.
• When you run go build on a main package, you get an executable file named after the directory (or your module name).
• When you run go install, it lands in your $GOPATH/bin or $GOBIN directory.

Library Packages

The library package does not use package main on top of their source code file. Their main purpose is to be exported and used by other code. They become dependencies that link into other programs. The standard library provided by go is a good example of library packages: fmt, net/http, os etc.

Why this distinction matters?

This distinction matters for your project structure. A well-organized Go project typically has one main package (often in cmd/myapp/) and multiple library packages (in internal/ and pkg/ directories) that contain the actual logic. This separation makes code reusable and testable.