Go Packages and Modules

Packages are Go's units of code organization. Every Go file belongs to a package. A module is a collection of related packages that are versioned and distributed together. Understanding packages and modules is essential for building real Go applications and working with third-party libraries.

What Is a Package?

A package groups related Go files in the same directory. All files in a directory must declare the same package name at the top.

myapp/
├── main.go          → package main
├── math/
│   └── calc.go      → package math
└── utils/
    └── helper.go    → package utils

Creating a Custom Package

Step 1 – Create the package file

File: math/calc.go

package math

// Add returns the sum of two integers.
// Exported functions start with a capital letter.
func Add(a, b int) int {
    return a + b
}

// Multiply returns the product of two integers.
func Multiply(a, b int) int {
    return a * b
}

// helper is unexported — only available inside this package
func helper() string {
    return "internal helper"
}

Step 2 – Use the package in main

File: main.go

package main

import (
    "fmt"
    "myapp/math"
)

func main() {
    fmt.Println(math.Add(10, 5))      // 15
    fmt.Println(math.Multiply(4, 3))  // 12
}

Exported vs Unexported Identifiers

Capital first letter  →  exported (visible outside the package)
Lowercase first letter →  unexported (visible only inside the package)

func Add(...)    → exported   — accessible from other packages
func helper(...) → unexported — private to the math package

type Rectangle  → exported
type config     → unexported

What Is a Module?

A module is a project root that contains a go.mod file. The module declares the project name and Go version, and tracks all external dependencies.

go mod init myapp

This creates go.mod:

module myapp

go 1.22

Module File Structure

myapp/
├── go.mod          ← module name, Go version, dependencies
├── go.sum          ← checksums for downloaded packages
├── main.go
└── math/
    └── calc.go

Adding an External Package

Use go get to download and add an external package to the project.

# Download the package
go get github.com/fatih/color

Go updates go.mod and go.sum automatically.

package main

import (
    "github.com/fatih/color"
)

func main() {
    color.Green("Hello in green!")
    color.Red("Error in red!")
}

Essential go mod Commands

The init Function

Each package can have an optional init function. Go calls it automatically before main starts. It is used for package-level setup like registering drivers or loading config.

package math

import "fmt"

func init() {
    fmt.Println("math package initialized")
}

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

Aliasing an Import

When two packages have the same name, or a name is too long, assign an alias.

import (
    "fmt"
    m "myapp/math"    // alias "math" as "m"
    _ "database/sql"  // blank import — triggers init() only
)

func main() {
    fmt.Println(m.Add(5, 3)) // 8
}

Key Points

• All files in the same directory belong to the same package
• Names starting with a capital letter are exported; lowercase names are private
• Every Go project starts with go mod init to create a module
• go.mod tracks the module name, Go version, and all dependencies
• Use go mod tidy to keep go.mod and go.sum clean and accurate
• The init function runs automatically before main for package setup