Golang package keyword

last modified May 7, 2025

This tutorial explains how to use the package keyword in Go. We'll cover package basics with practical examples of organizing Go code.

The package declaration defines a code module's namespace in Go. Every Go file must begin with a package declaration. It groups related functionality.

In Go, packages are the primary mechanism for code organization and reuse. They enable modular programming and control visibility of identifiers outside the package.

Basic package declaration

The simplest package declaration creates an executable program. The main package is special in Go as it defines an executable.

package main

import "fmt"

func main() {
    fmt.Println("Hello from main package")
}

This is the minimal package declaration for an executable Go program. The main function is the entry point when the package is compiled.

Creating a library package

Library packages provide reusable functionality. This example shows a simple math utility package.

package mathutil

// Add returns the sum of two integers
func Add(a, b int) int {
    return a + b
}

// Subtract returns the difference of two integers
func Subtract(a, b int) int {
    return a - b
}

The package name mathutil becomes the import path identifier. Exported functions start with uppercase letters, making them publicly accessible.

Importing and using packages

This example demonstrates importing and using our custom mathutil package from another file.

package main

import (
    "fmt"
    "./mathutil"
)

func main() {
    sum := mathutil.Add(5, 3)
    diff := mathutil.Subtract(5, 3)
    
    fmt.Printf("Sum: %d, Difference: %d\n", sum, diff)
}

The import statement loads the mathutil package. We access its functions using the package name as a prefix. The ./ denotes a local package.

Package initialization

Packages can have initialization logic using init functions. This example shows package-level variables and initialization.

package config

import "fmt"

var AppName string
var Version string

func init() {
    AppName = "MyApp"
    Version = "1.0.0"
    fmt.Println("Config package initialized")
}

package main

import (
    "fmt"
    "./config"
)

func main() {
    fmt.Printf("%s v%s\n", config.AppName, config.Version)
}

The init function runs automatically when the package is imported. Multiple init functions in a package execute in declaration order.

Nested package structure

Go supports nested package structures for better organization. This example shows a nested package hierarchy.

package stringutil

// Reverse returns its argument string reversed
func Reverse(s string) string {
    r := []rune(s)
    for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
        r[i], r[j] = r[j], r[i]
    }
    return string(r)
}

package main

import (
    "fmt"
    "mylib/stringutil"
)

func main() {
    fmt.Println(stringutil.Reverse("Hello, world!"))
}

The nested package stringutil is imported using its full path. Go tools automatically handle nested packages in the module system.

Internal packages

Go's internal packages restrict visibility to specific parent packages. This example demonstrates the internal package mechanism.

package internal

// SecretKey is only visible to mylib and its subpackages
var SecretKey = "very-secret-key"

// GetKey returns the secret key
func GetKey() string {
    return SecretKey
}

package auth

import "mylib/internal"

func Authenticate() string {
    return internal.GetKey()
}

The internal package is only importable by packages within the mylib directory tree. This provides encapsulation for internal implementation details.

Package documentation

Go packages support built-in documentation. This example shows proper package documentation practices.

// Package greeting provides functions for creating greetings.
// It demonstrates proper Go documentation conventions.
package greeting

import "fmt"

// Greet returns a personalized greeting
func Greet(name string) string {
    return fmt.Sprintf("Hello, %s!", name)
}

// GreetTime returns a greeting with current time
func GreetTime(name string, hour int) string {
    var timeOfDay string
    
    switch {
    case hour < 12:
        timeOfDay = "morning"
    case hour < 18:
        timeOfDay = "afternoon"
    default:
        timeOfDay = "evening"
    }
    
    return fmt.Sprintf("Good %s, %s!", timeOfDay, name)
}

The package comment appears immediately before the package declaration. Function comments start with the function name. These appear in generated documentation.

Source

Go language specification

This tutorial covered the package keyword in Go with practical examples of code organization and modular development.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Golang tutorials.