By now, you've probably noticed that as soon as you run go mod init, Go drops two files into your project folder: go.mod and go.sum. If you've come from Node.js or Python, these look familiar, but Go handles them in a way that's specifically designed to avoid "dependency hell." Let's break down what's actually happening inside those files.

What is the go.mod file actually doing?

Think of go.mod as the manifest for your project. It tells the Go toolchain exactly which module your project is, where it lives, and which specific versions of other libraries it needs to run. I like to think of it as the "source of truth."

Let's say we're building a small CLI tool that generates unique IDs and logs them. We'd use google/uuid for the IDs and sirupsen/logrus for the logging. Your go.mod would look something like this:

module github.com/yourname/id-logger

go 1.21

require (
	github.com/google/uuid v1.6.0
	github.com/sirupsen/logrus v1.9.3
)

The module line defines the path. The require block is where the magic happens. If you try to build the project on a different machine, Go looks at this file and says, "Right, I need exactly v1.6.0 of the uuid package," and goes to fetch it. It eliminates the "it works on my machine" excuse because everyone is pinned to the same versions.

If go.mod lists the versions, why do I need go.sum?

This is the part that trips people up. If go.mod says we need v1.6.0, why do we need another file? The answer is security and integrity.

The go.sum file isn't a version list; it's a list of SHA-256 checksums. When you download a module, Go calculates a hash of the code and records it in go.sum. The next time you (or a teammate) download that same version, Go checks the newly downloaded code against that hash. If a malicious actor somehow hijacked the library's repository and swapped the code in v1.6.0 with something nasty, the hashes wouldn't match, and Go would refuse to compile the project.

I've seen a few developers try to delete go.sum because it looks like "clutter." Don't do that. It's your insurance policy against supply chain attacks.

Should I be committing these files to version control?

Yes. A thousand times, yes. You should commit both go.mod and go.sum to Git.

If you don't commit them, you're forcing every other developer (and your CI/CD pipeline) to resolve dependencies from scratch. That leads to inconsistent builds and potential crashes if a dependency author deletes a tag or pushes a breaking change to a version. By committing both files, you ensure that the exact same bytes are being compiled on your laptop, your coworker's Mac, and your production Linux server.

How do I clean up the mess when I stop using a library?

You'll find that as you experiment, your go.mod file can get bloated with libraries you tried once but decided against. Just deleting the import statement in your .go files doesn't remove the requirement from go.mod.

This is where go mod tidy comes in. It's probably the most useful command in the module toolkit. When you run it, Go scans your entire project for imports, adds any missing modules to go.mod, and—more importantly—strips out any modules that are no longer being used. I usually run this as a habit before every single commit.

# Remove unused dependencies and sync go.sum
go mod tidy

📋 Practical Task

Exercise: Dependency Synchronization with UUID and Logrus

In this exercise, you will practice managing a project's dependency lifecycle by adding, using, and then pruning libraries.

1. Initialize a new module named github.com/username/dep-test.
2. Install the github.com/google/uuid and github.com/sirupsen/logrus packages using go get.
3. Create a main.go file that imports both packages, generates a new UUID, and logs it using logrus.
4. Run the program to ensure it works, and observe the contents of your go.mod and go.sum files.
5. Now, remove the logrus import and the code that uses it from main.go.
6. Notice that go.mod still lists logrus. Run go mod tidy in your terminal.
7. Verify that logrus has been removed from both go.mod and go.sum.