{"id":1086,"date":"2026-08-17T00:36:17","date_gmt":"2026-08-17T00:36:17","guid":{"rendered":"https:\/\/www.devopsschool.com\/tutorials\/?p=1086"},"modified":"2026-08-17T00:36:18","modified_gmt":"2026-08-17T00:36:18","slug":"go-tutorials-dependency-management-with-go-modules","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/tutorials\/go-tutorials-dependency-management-with-go-modules\/","title":{"rendered":"Go Tutorials: Dependency Management with Go Modules"},"content":{"rendered":"\n

Go Modules become much easier once you keep one mental model in mind:<\/p>\n\n\n\n

\n

Your Go source code says what packages you use. go.mod<\/code> says which modules\/versions provide them. go.sum<\/code> helps verify downloaded dependency content.<\/strong><\/p>\n<\/blockquote>\n\n\n\n

A module<\/strong> is normally your Go project or library together with its dependency information. go mod init<\/code> creates the module’s go.mod<\/code> file, while commands such as go get<\/code> and go mod tidy<\/code> keep dependency information synchronized with your source code. (Go.dev<\/a>)<\/p>\n\n\n\n

\n\n\n\n

1. What is dependency management?<\/h2>\n\n\n\n

Suppose your program needs to generate a UUID.<\/p>\n\n\n\n

You could write all the UUID logic yourself, or use an existing Go package:<\/p>\n\n\n\n

import \"github.com\/google\/uuid\"<\/code><\/pre>\n\n\n\n
Now your application depends on code from another project.<\/p>\n\n\n\n
That external code is a dependency<\/strong>.<\/p>\n\n\n\n
Go Modules manage:<\/p>\n\n\n\n
Your application\n      |\n      | imports\n      v\ngithub.com\/google\/uuid\n      |\n      | particular version\n      v\n    v1.6.0<\/code><\/pre>\n\n\n\n
The version of that dependency is recorded in your project’s go.mod<\/code>.<\/p>\n\n\n\n
\n\n\n\n
2. What \/ Why \/ When \/ How \/ Where<\/h1>\n\n\n\n
Question<\/th>Simple answer<\/th><\/tr><\/thead>
What?<\/strong><\/td>Go Modules are Go’s dependency-management system.<\/td><\/tr>
Why?<\/strong><\/td>To track external libraries and their versions reliably.<\/td><\/tr>
When?<\/strong><\/td>For practically every normal Go project that contains packages or external dependencies.<\/td><\/tr>
How?<\/strong><\/td>Start with go mod init<\/code>, add\/use dependencies, and maintain them with commands such as go get<\/code> and go mod tidy<\/code>.<\/td><\/tr>
Where?<\/strong><\/td>Dependency information lives mainly in go.mod<\/code> and go.sum<\/code> at the module root.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
\n\n\n\n
3. The three things to remember<\/h1>\n\n\n\n
Think of a Go project like this:<\/p>\n\n\n\n
go-mod-demo\/\n\u2502\n\u251c\u2500\u2500 go.mod\n\u251c\u2500\u2500 go.sum\n\u2514\u2500\u2500 main.go<\/code><\/pre>\n\n\n\n
main.go<\/code><\/h3>\n\n\n\n
Your actual Go source code.<\/p>\n\n\n\n
go.mod<\/code><\/h3>\n\n\n\n
Describes your module and records required module versions. (Go.dev<\/a>)<\/p>\n\n\n\n
Example:<\/p>\n\n\n\n
module example.com\/go-mod-demo\n\ngo 1.xx\n\nrequire github.com\/google\/uuid v1.6.0<\/code><\/pre>\n\n\n\n
Don’t worry about the exact go<\/code> version shown there; Go writes the appropriate value for your environment.<\/p>\n\n\n\n
go.sum<\/code><\/h3>\n\n\n\n
Contains cryptographic hashes associated with downloaded module dependencies so Go can verify dependency content. (Go.dev<\/a>)<\/p>\n\n\n\n
You normally do not manually edit go.sum<\/code><\/strong>.<\/p>\n\n\n\n
\n\n\n\n
4. Complete example \u2014 UUID generator<\/h1>\n\n\n\n
This is the only example you need for understanding the basic workflow.<\/p>\n\n\n\n
We will build:<\/p>\n\n\n\n
Go Program\n    |\n    | import\n    v\ngithub.com\/google\/uuid\n    |\n    v\nGenerate UUID<\/code><\/pre>\n\n\n\n
The example uses github.com\/google\/uuid<\/code> version v1.6.0<\/code>. That version provides uuid.NewString()<\/code>. (Chromium Git Repositories<\/a>)<\/p>\n\n\n\n
\n\n\n\n
Step 1 \u2014 Create the project<\/h2>\n\n\n\n
mkdir go-mod-demo\ncd go-mod-demo<\/code><\/pre>\n\n\n\n
\n\n\n\n
Step 2 \u2014 Initialize a Go module<\/h2>\n\n\n\n
Run:<\/p>\n\n\n\n
go mod init example.com\/go-mod-demo<\/code><\/pre>\n\n\n\n
You should now have:<\/p>\n\n\n\n
go-mod-demo\/\n\u2514\u2500\u2500 go.mod<\/code><\/pre>\n\n\n\n
The command:<\/p>\n\n\n\n
go mod init example.com\/go-mod-demo<\/code><\/pre>\n\n\n\n
means:<\/p>\n\n\n\n
go mod init\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500 Name\/path of our module\n\u2502   \u2502\n\u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500 Initialize\n\u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Go command<\/code><\/pre>\n\n\n\n
go mod init<\/code> creates a new go.mod<\/code> in the current directory and establishes that directory as the module root. (Go.dev<\/a>)<\/p>\n\n\n\n
\n\n\n\n
Step 3 \u2014 Create main.go<\/code><\/h1>\n\n\n\n
Create this file:<\/p>\n\n\n\n
package main\n\nimport (\n\t\"fmt\"\n\n\t\/\/ This package comes from an external Go module.\n\t\"github.com\/google\/uuid\"\n)\n\nfunc main() {\n\t\/\/ uuid.NewString() comes from the external dependency.\n\tid := uuid.NewString()\n\n\tfmt.Println(\"Generated UUID:\", id)\n}<\/code><\/pre>\n\n\n\n
That’s the complete application.<\/p>\n\n\n\n
Notice this line:<\/p>\n\n\n\n
\"github.com\/google\/uuid\"<\/code><\/pre>\n\n\n\n
Your application is saying:<\/p>\n\n\n\n
\n
“I need the uuid<\/code> package.”<\/p>\n<\/blockquote>\n\n\n\n
But Go still needs to know which module version<\/strong> should provide it.<\/p>\n\n\n\n
\n\n\n\n
Step 4 \u2014 Add the dependency<\/h1>\n\n\n\n
Run:<\/p>\n\n\n\n
go get github.com\/google\/uuid@v1.6.0<\/code><\/pre>\n\n\n\n
Now look at your folder:<\/p>\n\n\n\n
go-mod-demo\/\n\u2502\n\u251c\u2500\u2500 go.mod\n\u251c\u2500\u2500 go.sum\n\u2514\u2500\u2500 main.go<\/code><\/pre>\n\n\n\n
And go.mod<\/code> will contain a requirement for the dependency:<\/p>\n\n\n\n
require github.com\/google\/uuid v1.6.0<\/code><\/pre>\n\n\n\n
The important connection is:<\/p>\n\n\n\n
main.go\n   |\n   | import \"github.com\/google\/uuid\"\n   |\n   v\ngo.mod\n   |\n   | require github.com\/google\/uuid v1.6.0\n   |\n   v\nGo downloads dependency<\/code><\/pre>\n\n\n\n
go get<\/code> is one of Go’s standard ways to add or change a dependency version recorded for the module. (Go.dev<\/a>)<\/p>\n\n\n\n
\n\n\n\n
Step 5 \u2014 Run the application<\/h1>\n\n\n\n
go run .<\/code><\/pre>\n\n\n\n
Example output:<\/p>\n\n\n\n
Generated UUID: 550e8400-e29b-41d4-a716-446655440000<\/code><\/pre>\n\n\n\n
Your actual UUID will be different.<\/p>\n\n\n\n
You have now successfully used an external Go dependency.<\/p>\n\n\n\n
\n\n\n\n
Step 6 \u2014 Clean the dependencies<\/h1>\n\n\n\n
Run:<\/p>\n\n\n\n
go mod tidy<\/code><\/pre>\n\n\n\n
This is a very useful command.<\/p>\n\n\n\n
It essentially asks Go:<\/p>\n\n\n\n
\n
“Look at my source code and make sure go.mod<\/code> and go.sum<\/code> match what the project really needs.”<\/p>\n<\/blockquote>\n\n\n\n
go mod tidy<\/code> adds missing module requirements, removes requirements that are no longer needed, and updates relevant go.sum<\/code> entries. (Go.dev<\/a>)<\/p>\n\n\n\n
A good habit is:<\/p>\n\n\n\n
go mod tidy<\/code><\/pre>\n\n\n\n
after adding or removing imports.<\/p>\n\n\n\n
\n\n\n\n
5. The complete workflow<\/h1>\n\n\n\n
flowchart TD\n    A[\"Create Project\"] --> B[\"go mod init\"]\n    B --> C[\"go.mod created\"]\n    C --> D[\"Write Go code\"]\n    D --> E[\"Import external package\"]\n    E --> F[\"go get dependency@version\"]\n    F --> G[\"go.mod \/ go.sum updated\"]\n    G --> H[\"go run .\"]\n    H --> I[\"go mod tidy\"]<\/code><\/pre>\n\n\n\n
Or remember it simply as:<\/p>\n\n\n\n
CREATE PROJECT\n      \u2193\ngo mod init\n      \u2193\nWRITE CODE\n      \u2193\nimport dependency\n      \u2193\ngo get dependency\n      \u2193\ngo run .\n      \u2193\ngo mod tidy<\/code><\/pre>\n\n\n\n
\n\n\n\n
6. Understanding go.mod<\/code><\/h1>\n\n\n\n
Your file might conceptually look like:<\/p>\n\n\n\n
module example.com\/go-mod-demo\n\ngo 1.xx\n\nrequire github.com\/google\/uuid v1.6.0<\/code><\/pre>\n\n\n\n
Let’s decode it.<\/p>\n\n\n\n
module<\/code><\/h3>\n\n\n\n
module example.com\/go-mod-demo<\/code><\/pre>\n\n\n\n
This is the identity\/path of your module<\/strong>.<\/p>\n\n\n\n
Think:<\/p>\n\n\n\n
module = my project's module name<\/code><\/pre>\n\n\n\n
\n\n\n\n
go<\/code><\/h3>\n\n\n\n
go 1.xx<\/code><\/pre>\n\n\n\n
This records the Go language\/module compatibility version associated with the module.<\/p>\n\n\n\n
For now, let the Go tools manage it.<\/p>\n\n\n\n
\n\n\n\n
require<\/code><\/h3>\n\n\n\n
require github.com\/google\/uuid v1.6.0<\/code><\/pre>\n\n\n\n
Means:<\/p>\n\n\n\n
My project requires\n\ngithub.com\/google\/uuid\n\nat selected version\n\nv1.6.0<\/code><\/pre>\n\n\n\n
\n\n\n\n
7. Module vs Package<\/h1>\n\n\n\n
This distinction confuses many Go beginners.<\/p>\n\n\n\n
They are not the same thing<\/strong>.<\/p>\n\n\n\n
Module<\/th>Package<\/th><\/tr><\/thead>
Collection of one or more related Go packages<\/td>Go source code in a directory<\/td><\/tr>
Has a go.mod<\/code> at its root<\/td>Declared with package xyz<\/code><\/td><\/tr>
Used for dependency\/version management<\/td>Used for organizing and importing Go code<\/td><\/tr>
Example: github.com\/google\/uuid<\/code> module<\/td>Example: the uuid<\/code> package you import<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Simple mental model:<\/p>\n\n\n\n
Module\n\u2502\n\u251c\u2500\u2500 Package A\n\u251c\u2500\u2500 Package B\n\u2514\u2500\u2500 Package C<\/code><\/pre>\n\n\n\n
A dependency is normally managed at the module level<\/strong>, even though your code imports packages<\/strong>.<\/p>\n\n\n\n
\n\n\n\n
8. go.mod<\/code> vs go.sum<\/code><\/h1>\n\n\n\n
go.mod<\/code><\/th>go.sum<\/code><\/th><\/tr><\/thead>
Describes your module<\/td>Contains dependency verification hashes<\/td><\/tr>
Records required module versions<\/td>Helps verify downloaded module content<\/td><\/tr>
Human-readable dependency configuration<\/td>Mostly maintained automatically<\/td><\/tr>
Important to commit to Git<\/td>Normally committed to Git too<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Think:<\/p>\n\n\n\n
go.mod\n\"What dependencies should I use?\"\n\ngo.sum\n\"Can I verify the dependency content I downloaded?\"<\/code><\/pre>\n\n\n\n
\n\n\n\n
9. Important commands compared<\/h1>\n\n\n\n
Command<\/th>Purpose<\/th>When you use it<\/th><\/tr><\/thead>
go mod init<\/code><\/td>Create a new module<\/td>At project creation<\/td><\/tr>
go get package@version<\/code><\/td>Add\/change a dependency<\/td>When adding or changing dependencies<\/td><\/tr>
go mod tidy<\/code><\/td>Synchronize dependency files with source code<\/td>After dependency\/import changes<\/td><\/tr>
go run .<\/code><\/td>Compile and run the current package<\/td>During development<\/td><\/tr>
go build<\/code><\/td>Compile your project<\/td>When you want a binary\/build check<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
The three module commands worth memorizing first are:<\/p>\n\n\n\n
go mod init\ngo get\ngo mod tidy<\/code><\/pre>\n\n\n\n
Everything else can come later.<\/p>\n\n\n\n
\n\n\n\n
10. What happens if you remove the dependency?<\/h1>\n\n\n\n
Suppose you change main.go<\/code> to:<\/p>\n\n\n\n
package main\n\nimport \"fmt\"\n\nfunc main() {\n\tfmt.Println(\"Hello\")\n}<\/code><\/pre>\n\n\n\n
There is no longer:<\/p>\n\n\n\n
import \"github.com\/google\/uuid\"<\/code><\/pre>\n\n\n\n
Run:<\/p>\n\n\n\n
go mod tidy<\/code><\/pre>\n\n\n\n
Go sees:<\/p>\n\n\n\n
Source code\n    |\n    X  no UUID import\n    |\ngo.mod<\/code><\/pre>\n\n\n\n
and can remove the now-unneeded UUID module requirement. This source-driven synchronization is exactly what go mod tidy<\/code> is designed to do. (Go.dev<\/a>)<\/p>\n\n\n\n
\n\n\n\n
11. Direct vs indirect dependencies<\/h1>\n\n\n\n
You may eventually see:<\/p>\n\n\n\n
require (\n    github.com\/google\/uuid v1.6.0\n    example.com\/something v1.2.3 \/\/ indirect\n)<\/code><\/pre>\n\n\n\n
Don’t let this confuse you.<\/p>\n\n\n\n
Direct<\/h3>\n\n\n\n
Your code directly imports it:<\/p>\n\n\n\n
import \"github.com\/google\/uuid\"<\/code><\/pre>\n\n\n\n
YOUR PROGRAM\n     \u2193\n    UUID<\/code><\/pre>\n\n\n\n
Indirect<\/h3>\n\n\n\n
Your dependency needs another module:<\/p>\n\n\n\n
YOUR PROGRAM\n     \u2193\nDependency A\n     \u2193\nDependency B<\/code><\/pre>\n\n\n\n
Dependency B can appear as:<\/p>\n\n\n\n
\/\/ indirect<\/code><\/pre>\n\n\n\n
An indirect requirement indicates that the main module does not directly import a package from that module, though it is needed through the dependency graph. (Go.dev<\/a>)<\/p>\n\n\n\n
For now:<\/p>\n\n\n\n
\n
Don’t manually manage \/\/ indirect<\/code>. Let Go do it.<\/strong><\/p>\n<\/blockquote>\n\n\n\n
\n\n\n\n
12. One golden rule<\/h1>\n\n\n\n
Don’t think:<\/p>\n\n\n\n
\n
“I need to manually maintain a big dependency file.”<\/p>\n<\/blockquote>\n\n\n\n
Instead think:<\/p>\n\n\n\n
Write imports\n      \u2193\nGo examines your code\n      \u2193\nGo manages module requirements\n      \u2193\ngo.mod + go.sum<\/code><\/pre>\n\n\n\n
Use the Go commands instead of manually editing dependency information unless you have a specific reason to do otherwise. The official Go documentation also recommends managing dependencies through Go commands so that go.mod<\/code> stays consistent. (Go.dev<\/a>)<\/p>\n\n\n\n
\n\n\n\n
13. Your everyday workflow<\/h1>\n\n\n\n
For a new project<\/strong>:<\/p>\n\n\n\n
mkdir myapp\ncd myapp\n\ngo mod init example.com\/myapp<\/code><\/pre>\n\n\n\n
Write code.<\/p>\n\n\n\n
If you need a dependency:<\/p>\n\n\n\n
go get dependency@version<\/code><\/pre>\n\n\n\n
Then:<\/p>\n\n\n\n
go run .<\/code><\/pre>\n\n\n\n
And periodically:<\/p>\n\n\n\n
go mod tidy<\/code><\/pre>\n\n\n\n
That’s enough for learning Go Modules initially.<\/p>\n\n\n\n
\n\n\n\n
14. Final cheat sheet<\/h1>\n\n\n\n
You want to…<\/th>Use<\/th><\/tr><\/thead>
Start dependency management<\/td>go mod init<\/code><\/td><\/tr>
Add\/change a dependency<\/td>go get<\/code><\/td><\/tr>
Clean dependency information<\/td>go mod tidy<\/code><\/td><\/tr>
See your dependencies<\/td>Open go.mod<\/code><\/td><\/tr>
Understand integrity information<\/td>Look at go.sum<\/code><\/td><\/tr>
Use a dependency in code<\/td>import \"...\"<\/code><\/td><\/tr>
Run the program<\/td>go run .<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Remember this sentence<\/h3>\n\n\n\n
\n
main.go<\/code> uses packages \u2192 go.mod<\/code> tracks required modules\/versions \u2192 go.sum<\/code> helps verify downloaded dependency content \u2192 go mod tidy<\/code> keeps everything synchronized.<\/strong><\/p>\n<\/blockquote>\n\n\n\n
If that sentence makes sense, you understand the core of dependency management using Go Modules<\/strong>. (Go.dev<\/a>)<\/p>\n","protected":false},"excerpt":{"rendered":"
Go Modules become much easier once you keep one mental model in mind: Your Go source code says what packages you use. go.mod says which modules\/versions provide… <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-1086","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/posts\/1086","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/comments?post=1086"}],"version-history":[{"count":1,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/posts\/1086\/revisions"}],"predecessor-version":[{"id":1087,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/posts\/1086\/revisions\/1087"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/media?parent=1086"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/categories?post=1086"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/tutorials\/wp-json\/wp\/v2\/tags?post=1086"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}