Packages & Modules

Packages: directories of related code

In Go, a package is simply a directory full of .go files that all declare the same package <name> at the top. That's it. No __init__.py, no class hierarchy, no manifest file. The directory is the package.

• All .go files in the same directory share the same package scope - they can call each other's functions and access each other's types directly, as if they were one big file.
• Go enforces one package per directory. Mixing package foo and package bar in the same directory is a compile error.
• The package name in the package declaration is usually (but not always) the same as the directory name.

# myapp/utils/__init__.py  (required)
# myapp/utils/strings.py
def truncate(s, n):
    return s[:n]

# myapp/utils/numbers.py
def clamp(x, lo, hi):
    return max(lo, min(hi, x))

# to use both:
from myapp.utils.strings import truncate
from myapp.utils.numbers import clamp

// myapp/utils/strings.go
package utils

func Truncate(s string, n int) string {
    return s[:n]
}

// myapp/utils/numbers.go
package utils

func Clamp(x, lo, hi int) int { ... }

// to use both - one import:
import "github.com/sunilt/myapp/utils"

Modules: versioned bundles of packages

A module is a tree of packages that are versioned and released together. It is defined by a go.mod file at the root of the tree. Think of it as the container that wraps your entire project - and declares what external code it depends on.

module github.com/sunilt/myapp

go 1.23

require (
    github.com/spf13/cobra v1.7.0
    k8s.io/client-go       v0.28.4
)

Three things in every go.mod:

• module path - the canonical import prefix for all packages in this module. Usually a GitHub URL, but it can be anything. This is what others write in their import statements.
• go version - minimum Go version required. Not a runtime check, just a signal to tooling.
• require - explicit list of external modules and their exact versions. No magic ranges, no "^1.x" wildcards. Exact versions only.

Module commands

$ go mod init github.com/you/myapp

$ go get github.com/spf13/cobra@v1.7.0

$ go mod tidy

# requirements.txt
click==8.1.7
requests==2.31.0

# setup.py (or pyproject.toml)
setup(
  name="myapp",
  version="1.0.0",
  install_requires=["click", "requests"],
)

# two separate files, often out of sync

module github.com/sunilt/myapp

go 1.23

require (
    github.com/spf13/cobra v1.7.0
    github.com/pkg/errors  v0.9.1
)

// go.sum holds cryptographic hashes
// run "go mod tidy" to keep in sync

The exported names rule (capitalization = visibility)

This is the Go quirk that surprises every Python developer. Go has no public / private keywords. Instead, the first letter of a name determines its visibility:

• Uppercase first letter = exported (public - any package can use it)
• Lowercase first letter = unexported (package-private - invisible outside the package)

This applies to everything: functions, types, struct fields, methods, constants, and package-level variables.

package utils

// Exported - other packages can call this
func Add(a, b int) int { return a + b }

// Unexported - only code inside package utils can call this
func validate(n int) bool { return n > 0 }

// Exported type with a mix of exported and unexported fields
type Counter struct {
    Value   int    // exported - anyone can read/set
    lastRun string // unexported - internal detail
}

# Leading underscore = "please don't"
# but Python won't stop you
def _internal_helper():
    pass

# Callers can still do:
from mymod import _internal_helper
_internal_helper()  # works, no error

// lowercase = hard boundary
func internalHelper() { ... }

// From another package:
import "github.com/x/mymod"
mymod.internalHelper()
// compile error:
// cannot refer to unexported name
// mymod.internalHelper

Importing: by path, not by name

Go imports use the full module path as the import string. The package name you use in code is just the last segment (usually), but the import string itself is the full URL-like path.

package main

import (
    "fmt"                                 // stdlib - short path
    "net/http"                            // stdlib - slash = subdirectory
    "github.com/spf13/cobra"              // external - full module path
    "github.com/sunilt/myapp/utils"        // your own subpackage

    f   "fmt"                             // alias: use as f.Println(...)
    _   "github.com/lib/pq"               // blank import: run init(), discard name
)

Import forms

import os
from os import path
from os.path import join, exists
import requests as req

# use:
os.getcwd()
req.get("https://...")

import (
    "os"
    "path/filepath"
    req "github.com/go-resty/resty/v2"
)

// use:
os.Getwd()
filepath.Join("a", "b")
req.New().Get("https://...")

The standard library tour

Go's standard library is famously comprehensive. You can write HTTP servers, parse JSON, manipulate CSV, run structured logging, and do cryptography - all without a single external dependency. This is deliberate: the Go team maintains and stabilizes the stdlib across versions, so your code doesn't break when npm/pip dependency drama happens.

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "strings"
)

type Person struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func main() {
    // encoding/json - marshal a struct
    p := Person{Name: "Sunil", Email: "sunilt@nvidia.com"}
    b, _ := json.Marshal(p)
    fmt.Println(string(b)) // {"name":"Sunil","email":"sunilt@nvidia.com"}

    // strings - manipulation
    words := strings.Split("go is fun", " ")
    fmt.Println(words) // [go is fun]

    // os - environment variable
    home := os.Getenv("HOME")
    fmt.Println(home)

    // net/http - a complete server in one call
    http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "ok")
    })
    http.ListenAndServe(":8080", nil)
}

Project layout: a sensible default

Go does not mandate a project structure. But the community has converged on a standard layout that works well for services and CLIs. This is a community convention, not a compiler rule - feel free to adapt it.

What each directory means

Real-world examples

package main

import (
    "log"
    "net/http"

    "github.com/sunilt/myapp/internal/handlers"
    "github.com/sunilt/myapp/internal/store"
)

func main() {
    db := store.New()
    h  := handlers.New(db)

    http.HandleFunc("/users", h.ListUsers)
    http.HandleFunc("/users/", h.GetUser)

    log.Println("Listening on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

package main

import (
    "fmt"
    "os"

    "github.com/spf13/cobra"
)

func main() {
    root := &cobra.Command{
        Use:   "mytool",
        Short: "A demo CLI",
    }

    greet := &cobra.Command{
        Use:   "greet [name]",
        Short: "Greet someone",
        RunE: func(cmd *cobra.Command, args []string) error {
            name := "world"
            if len(args) > 0 {
                name = args[0]
            }
            fmt.Printf("Hello, %s!\n", name)
            return nil
        },
    }

    root.AddCommand(greet)
    if err := root.Execute(); err != nil {
        os.Exit(1)
    }
}

$ go mod init github.com/sunilt/mytool
$ go get github.com/spf13/cobra@v1.7.0
$ go run ./cmd/mytool greet Sunil
Hello, Sunil!

package main

import (
    "context"
    "fmt"
    "log"

    corev1  "k8s.io/api/core/v1"             // k8s API types
    metav1  "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/kubernetes"
    "k8s.io/client-go/tools/clientcmd"
)

func main() {
    config, err := clientcmd.BuildConfigFromFlags("", "~/.kube/config")
    if err != nil {
        log.Fatal(err)
    }

    cs, err := kubernetes.NewForConfig(config)
    if err != nil {
        log.Fatal(err)
    }

    pods, err := cs.CoreV1().Pods("").List(
        context.Background(),
        metav1.ListOptions{},
    )
    if err != nil {
        log.Fatal(err)
    }

    for _, pod := range pods.Items {
        var p corev1.Pod = pod
        fmt.Printf("%s/%s\n", p.Namespace, p.Name)
    }
}

Gotchas

Glossary

Origins, gotchas, and a quick check

Backstory and pitfalls that make this chapter stick.

// file: greet.go
package main

import "fmt"

type user struct {
    name string
}

func main() {
    u := user{name: "Alice"}
    fmt.Println(greet(u))
}

// file: greeter.go
package main

import "fmt"

func greet(u user) string {
    return fmt.Sprintf("Hello, %s!", u.Name)
}

Quick check