Go makes it easy to organize code into reusable and maintainable parts using packages and modules.

If you are new to Go, these two terms can feel confusing because they are related but not the same.

A package is a group of Go files that belong together.

A module is a collection of related Go packages managed as one project or dependency unit.

In simple terms:

Module
 ├── Package
 ├── Package
 └── Package

In this guide, you will learn what packages and modules are in Go, how they work, how to create them, how to import packages, how go.mod works, how dependencies are managed, and how to structure a simple Go project.

---

What Is a Package in Go?

A package is a group of related Go source files.

Every Go file belongs to a package.

You declare the package at the top of the file.

Example:

package main

Another example:

package utils

Files that belong to the same package usually work together and can share exported and unexported identifiers according to Go’s visibility rules.

For example, you might create separate packages for:

• User logic
• Database logic
• Authentication
• Utilities
• Payment logic
• API handlers

Packages help you divide a large application into smaller, manageable sections.

---

Why Are Packages Used in Go?

Packages are mainly used to organize and reuse code.

Without packages, a large Go project could become difficult to maintain because everything would be placed in the same location.

Packages help you:

• Separate different parts of your application
• Reuse functions and types
• Keep code easier to understand
• Avoid large files
• Share functionality between different parts of a project
• Use code from the Go standard library
• Use third-party libraries

For example, instead of placing all math-related functions in main.go, you could create a package called:

calculator

and store those functions there.

---

The main Package

Go programs that build into executable applications usually use the main package.

Example:

package main

import "fmt"

func main() {
    fmt.Println("Hello Go")
}

The important parts are:

package main

and:

func main()

The main package tells Go that this code belongs to an executable program.

The main() function is the entry point of that program.

---

Creating Your Own Package

Suppose you have this project:

myapp/
├── main.go
└── calculator/
    └── calculator.go

Inside:

calculator/calculator.go

write:

package calculator

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

Now your main.go can import and use this package.

Example:

package main

import (
    "fmt"
    "example.com/myapp/calculator"
)

func main() {
    result := calculator.Add(10, 20)

    fmt.Println(result)
}

Output:

30

This is a basic example of creating and using your own Go package.

---

Package Naming in Go

Package names are usually short and descriptive.

Examples:

fmt
http
json
math
strings
time

Custom package examples:

user
payment
database
auth
config
utils

A package declaration looks like:

package payment

When importing it, you usually refer to it using the package name:

payment.Process()

---

Exported and Unexported Names

Go uses capitalization to control whether a function, variable, type, or field can be accessed from another package.

If the name starts with an uppercase letter, it is exported.

Example:

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

Because Add starts with uppercase A, another package can use it.

Example:

calculator.Add(10, 20)

But this function:

func subtract(a int, b int) int {
    return a - b
}

starts with lowercase s.

It is unexported and can only be accessed from inside the same package.

This rule also applies to:

• Functions
• Variables
• Constants
• Structs
• Struct fields
• Methods

---

Importing Packages in Go

Go uses the import keyword to use code from another package.

Example:

import "fmt"

Then:

fmt.Println("Hello Go")

You can import multiple packages using parentheses.

Example:

import (
    "fmt"
    "strings"
    "time"
)

Now you can use:

fmt.Println("Hello")
strings.ToUpper("go")
time.Now()

---

Importing Standard Library Packages

Go includes a large standard library.

Common examples include:

import (
    "fmt"
    "math"
    "strings"
    "time"
)

Example:

package main

import (
    "fmt"
    "strings"
)

func main() {
    text := "hello go"

    fmt.Println(strings.ToUpper(text))
}

Output:

HELLO GO

Here:

fmt

and:

strings

are standard library packages.

---

Importing Your Own Package

Suppose your module path is:

example.com/myapp

and your project contains:

myapp/
├── go.mod
├── main.go
└── greeting/
    └── greeting.go

Inside greeting.go:

package greeting

func Hello(name string) string {
    return "Hello " + name
}

Now import it in main.go:

package main

import (
    "fmt"
    "example.com/myapp/greeting"
)

func main() {
    message := greeting.Hello("Ankit")

    fmt.Println(message)
}

Output:

Hello Ankit

---

What Is a Module in Go?

A module is a collection of Go packages that are versioned and managed together.

A Go module usually represents one project.

For example:

myapp/
├── go.mod
├── main.go
├── user/
├── payment/
└── database/

All these packages can belong to one module.

The module is defined using a file named:

go.mod

---

Package vs Module in Go

This is one of the most important differences to understand.

Feature	Package	Module
Purpose	Organize related Go files	Organize and manage packages
Contains	Go files	One or more packages
Defined by	package keyword	go.mod file
Example	package auth	module example.com/myapp
Used for	Code organization	Dependency and project management

A simple way to remember it is:

Package = group of related Go files

Module = group of related Go packages

---

Creating a Go Module

To create a new module, open a terminal inside your project folder.

Example:

mkdir myapp
cd myapp

Initialize the module:

go mod init example.com/myapp

Go creates:

go.mod

The file may look like:

module example.com/myapp

go 1.25

The exact Go version depends on the version you are using.

---

What Is the go.mod File?

The go.mod file describes your Go module.

It contains important information such as:

• Module path
• Go language version
• Required dependencies

Example:

module example.com/myapp

go 1.25

If your application uses external dependencies, they may also appear here.

Example:

module example.com/myapp

go 1.25

require example.com/somepackage v1.2.3

You normally do not need to manually manage every dependency entry because Go commands can update this file automatically.

---

What Is a Module Path?

A module path uniquely identifies your module.

Example:

github.com/username/project

or:

example.com/myapp

When you run:

go mod init github.com/username/project

your go.mod contains:

module github.com/username/project

Your internal packages can then be imported using this module path.

For example:

import "github.com/username/project/auth"

---

Creating a Simple Go Module

Let’s build a basic module.

Project structure:

calculatorapp/
├── go.mod
├── main.go
└── calculator/
    └── calculator.go

Initialize it:

go mod init example.com/calculatorapp

Now:

go.mod

contains something similar to:

module example.com/calculatorapp

go 1.25

Inside:

calculator/calculator.go

write:

package calculator

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

func Multiply(a int, b int) int {
    return a * b
}

Then inside main.go:

package main

import (
    "fmt"
    "example.com/calculatorapp/calculator"
)

func main() {
    fmt.Println(calculator.Add(10, 5))
    fmt.Println(calculator.Multiply(10, 5))
}

Output:

15
50

This shows how one module can contain multiple packages.

---

Multiple Files in the Same Package

A package can contain multiple .go files.

For example:

calculator/
├── add.go
├── subtract.go
└── multiply.go

Inside add.go:

package calculator

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

Inside subtract.go:

package calculator

func Subtract(a int, b int) int {
    return a - b
}

Inside multiply.go:

package calculator

func Multiply(a int, b int) int {
    return a * b
}

All three files use:

package calculator

so they belong to the same package.

Another package can use all exported functions:

calculator.Add(10, 5)
calculator.Subtract(10, 5)
calculator.Multiply(10, 5)

---

Package Folder and Package Name

Usually, the folder name and package name are the same.

For example:

auth/
    auth.go

Inside:

package auth

This is the common and recommended approach.

It keeps imports easy to understand.

---

Using Third-Party Packages

Go can also use external packages created by other developers.

You usually import the dependency inside your Go code.

For example:

import "example.com/library"

Then run:

go mod tidy

Go will inspect your imports and update module dependencies as needed.

In real projects, third-party module paths commonly come from Git hosting platforms or package repositories.

---

What Does go get Do?

The go get command is commonly used when adding or changing module dependencies.

Example:

go get example.com/library

It can update dependency information in:

go.mod

and:

go.sum

You can also request a particular version when needed.

Example:

go get example.com/library@v1.2.3

---

What Does go mod tidy Do?

One of the most useful module commands is:

go mod tidy

It helps keep your module files clean.

It can:

• Add dependencies required by your code
• Remove dependencies that are no longer required
• Update module metadata

After adding or removing imports, running:

go mod tidy

is a common practice.

---

What Is go.sum?

When external dependencies are used, you may see:

go.sum

alongside:

go.mod

Example structure:

myapp/
├── go.mod
├── go.sum
└── main.go

The go.sum file contains checksums related to module dependencies.

These checksums help Go verify that downloaded module content matches expected versions.

You normally should not edit go.sum manually.

Go manages it for you.

---

go.mod vs go.sum

These files have different purposes.

File	Purpose
go.mod	Defines module and dependencies
go.sum	Stores dependency checksums

Think of:

go.mod

as the module configuration.

And:

go.sum

as verification information for dependencies.

---

Common Go Module Commands

Here are some important commands you will frequently use.

Command	Purpose
go mod init	Create a new module
go mod tidy	Add/remove required dependencies
go get	Add or update dependencies
go list -m all	List modules used by the project
go mod download	Download module dependencies
go mod graph	Show module dependency graph

For beginners, the most important commands are:

go mod init
go mod tidy
go get

---

Import Aliases

You can give an imported package a different local name.

Example:

import f "fmt"

Then:

f.Println("Hello")

Another example:

import jsonutil "encoding/json"

Then:

jsonutil.Marshal(data)

Aliases can be useful when two packages have the same package name or when a clearer local name is helpful.

However, unnecessary aliases can make code harder to read.

---

Blank Imports

Go also supports a blank import using _.

Example:

import _ "example.com/driver"

A blank import loads a package for its side effects without directly referencing its exported names.

This is common with some drivers and plugin-style packages.

For beginners, you do not need to use blank imports often.

---

The init() Function in Packages

A package can contain an init() function.

Example:

package config

import "fmt"

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

The init() function runs automatically during package initialization.

You do not call it manually.

A simple program could look like:

package main

import "fmt"

func init() {
    fmt.Println("Initializing application")
}

func main() {
    fmt.Println("Application started")
}

Output:

Initializing application
Application started

For beginner applications, use init() carefully and prefer explicit initialization when that makes the program easier to understand.

---

Internal Packages

Go supports a special directory named:

internal

Example:

myapp/
├── go.mod
├── main.go
└── internal/
    └── auth/
        └── auth.go

Packages inside an internal directory have restricted import visibility.

They are useful when you want code to remain private to a particular module or part of a project.

A common project structure might look like:

myapp/
├── go.mod
├── main.go
├── internal/
│   ├── auth/
│   └── database/
└── pkg/
    └── utility/

Beginners do not need to use this structure immediately, but understanding internal becomes useful as projects grow.

---

A Simple Go Project Structure

For a small project, you can keep things simple.

Example:

myapp/
├── go.mod
├── main.go
├── user/
│   └── user.go
└── calculator/
    └── calculator.go

Your go.mod might contain:

module example.com/myapp

go 1.25

Inside:

user/user.go

you might have:

package user

type User struct {
    Name string
    Age  int
}

Inside:

calculator/calculator.go

you might have:

package calculator

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

Then main.go can use both:

package main

import (
    "fmt"

    "example.com/myapp/calculator"
    "example.com/myapp/user"
)

func main() {
    u := user.User{
        Name: "Ankit",
        Age:  24,
    }

    result := calculator.Add(10, 20)

    fmt.Println(u.Name)
    fmt.Println(result)
}

Output:

Ankit
30

---

Practical Example: Greeting Package

Let’s create a reusable greeting package.

Project:

greetingapp/
├── go.mod
├── main.go
└── greeting/
    └── greeting.go

Initialize:

go mod init example.com/greetingapp

Inside greeting/greeting.go:

package greeting

func Hello(name string) string {
    return "Hello, " + name
}

func Goodbye(name string) string {
    return "Goodbye, " + name
}

Inside main.go:

package main

import (
    "fmt"

    "example.com/greetingapp/greeting"
)

func main() {
    fmt.Println(greeting.Hello("Ankit"))
    fmt.Println(greeting.Goodbye("Ankit"))
}

Output:

Hello, Ankit
Goodbye, Ankit

---

Practical Example: Calculator Module

Create:

calculatorapp/
├── go.mod
├── main.go
└── mathutils/
    └── mathutils.go

Inside:

mathutils/mathutils.go

write:

package mathutils

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

func Subtract(a int, b int) int {
    return a - b
}

Then:

package main

import (
    "fmt"

    "example.com/calculatorapp/mathutils"
)

func main() {
    fmt.Println(mathutils.Add(20, 10))
    fmt.Println(mathutils.Subtract(20, 10))
}

Output:

30
10

---

Common Mistakes with Go Packages

1. Using Lowercase Names for Exported Functions

Suppose you create:

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

Another package cannot call:

calculator.add(10, 20)

because add is unexported.

Use:

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

---

2. Using Different Package Names in the Same Folder

Suppose one file contains:

package calculator

and another regular Go file in the same directory contains:

package mathutils

This usually causes a package conflict.

Files in the same normal package directory should use the same package name.

---

3. Wrong Import Path

If your go.mod says:

module example.com/myapp

and your package is:

calculator/

the import should be:

import "example.com/myapp/calculator"

Using an unrelated path will fail.

---

Common Mistakes with Go Modules

1. Forgetting to Initialize a Module

If you are building a normal module-based project, initialize it with:

go mod init example.com/myapp

This creates the go.mod file.

---

2. Editing Dependency Files Manually Without Need

Go normally manages:

go.mod
go.sum

through commands such as:

go get
go mod tidy

Manual changes are sometimes possible, but beginners should usually let Go manage dependency entries.

---

3. Forgetting go mod tidy

After changing imports, your dependency files may need updating.

Run:

go mod tidy

to synchronize dependencies with your source code.

---

Packages vs Modules vs Files

These concepts can be summarized like this:

Module
│
├── Package A
│   ├── file1.go
│   └── file2.go
│
├── Package B
│   └── file3.go
│
└── Package C
    └── file4.go

A .go file belongs to a package.

A package contains one or more Go files.

A module contains one or more packages.

---

Standard Package vs Custom Package vs Third-Party Package

Go developers commonly work with three types of packages.

Standard Library Package

Built into Go.

Example:

import "fmt"

Custom Package

Created inside your project.

Example:

import "example.com/myapp/auth"

Third-Party Package

Created outside your project and added as a dependency.

Example structure:

import "example.com/external/package"

Modules help Go manage these external dependencies.

---

Best Practices for Go Packages and Modules

When working with packages and modules, follow these basic practices:

1. Keep package names short and meaningful.
2. Group related functionality inside the same package.
3. Use uppercase names only for identifiers that need to be exported.
4. Avoid creating too many tiny packages without a clear reason.
5. Keep your module path consistent with your imports.
6. Run go mod tidy after changing dependencies.
7. Do not manually edit go.sum.
8. Use modules to manage project dependencies.
9. Keep small projects simple before adopting complex folder structures.
10. Import only packages that your code actually uses.

---

Frequently Asked Questions

What is a package in Go?

A package is a collection of related Go files.

Every Go file starts with a package declaration such as:

package main

or:

package calculator

---

What is a module in Go?

A module is a collection of related Go packages managed together.

A module is defined using:

go.mod

---

What is the difference between a package and a module?

A package organizes related Go files.

A module organizes and manages one or more packages.

---

What does go mod init do?

It initializes a new Go module.

Example:

go mod init example.com/myapp

This creates a:

go.mod

file.

---

What is go.mod?

go.mod is the main module configuration file.

It defines:

• Module path
• Go version
• Module dependencies

---

What is go.sum?

go.sum contains checksums for module dependencies.

Go uses these values to help verify dependency content.

---

What does go mod tidy do?

It synchronizes module dependencies with the imports used by your code.

Run:

go mod tidy

It can add missing dependencies and remove unused ones.

---

What does go get do?

go get can add or change module dependencies.

Example:

go get example.com/library

---

Can one module contain multiple packages?

Yes.

Example:

myapp/
├── auth/
├── database/
├── user/
└── payment/

All these packages can belong to the same module.

---

Can one package have multiple Go files?

Yes.

Example:

calculator/
├── add.go
├── subtract.go
└── multiply.go

As long as those regular files belong to the same package, they can work together.

---

What is package main?

package main is used for executable Go programs.

It normally contains:

func main() {
}

which is the program entry point.

---

Conclusion

Packages and modules are essential for organizing Go projects.

A package groups related Go source files.

For example:

package calculator

A module groups and manages related packages.

You create a module using:

go mod init example.com/myapp

which creates:

go.mod

Your project might then look like:

myapp/
├── go.mod
├── main.go
├── auth/
├── user/
└── database/

The easiest way to remember the difference is:

Files belong to packages.

Packages belong to modules.

Once you understand packages, imports, go.mod, go.sum, go mod init, go get, and go mod tidy, organizing and managing Go projects becomes much easier.