Importing Local Packages in Go: A Step-by-Step Guide with Code

Why does importing local packages in Go raise so many questions?

If you've ever tried to organize Go code into separate files and folders, you've likely encountered an error like could not import "myproject/utils". This is one of the most common problems for beginner Go developers. On Stack Overflow, the question "How to import local packages in go?" has garnered thousands of views — and for good reason.

Unlike Python, where you can simply place a file nearby and write import mymodule, Go requires a clear structure and proper module configuration. But once you master this mechanism, you'll understand how elegant it is. Let's figure it out once and for all.

Brief Theory: How Go Understands Packages

Before writing code, remember three key principles:

\n
• Go is a language with a strict modular structure. Each directory is one package.
\n
• The package name does not have to match the folder name, but it is strongly recommended for readability.
\n
• Importing local packages since 2019 is done via modules (Go modules). Forget about GOPATH — use go mod.
\n

Now let's move on to practice.

Step 1: Create a Project with a Module

Open your terminal and create a new folder for your project:

mkdir go-local-imports\ncd go-local-imports\n

Now initialize the module. The module name can be anything, but it's logical to use a path that will be unique (e.g., a link to a repository):

go mod init github.com/your-username/go-local-imports\n

After this command, a go.mod file will appear in the folder. This file will manage dependencies — both local and external.

Step 2: Create a Local Package

Let's create a utils folder inside the project. Inside it, create a file math.go:

mkdir utils\ncd utils\ntouch math.go\n

Open utils/math.go and write:

package utils\n\n// Add returns the sum of two integers\nfunc Add(a, b int) int {\n    return a + b\n}\n

Note: the function Add is written with a capital letter. In Go, this means it is exported (public). If you write add — it will be private and inaccessible from other packages.

Step 3: Import and Use the Local Package

Go back to the root folder of the project and create main.go:

cd ..\ntouch main.go\n

Contents of main.go:

package main\n\nimport (\n    "fmt"\n    "github.com/your-username/go-local-imports/utils"\n)\n\nfunc main() {\n    result := utils.Add(3, 5)\n    fmt.Println("Sum:", result)\n}\n

Now run the program:

go run main.go\n

You should see:

Sum: 8\n

Everything works! But if you got an error — read the next section.

Common Errors and Their Solutions

Error 1: "package is not in GOROOT"

You see something like:

package myproject/utils is not in GOROOT (/usr/local/go/src/myproject/utils)

Cause: You are trying to import a package without a module. Go looks for it in the standard library, not in your project.

Solution: Make sure there is a go.mod file in the project root. If not, run go mod init module-name.

Error 2: "undefined: utils.Add"

Cause: The function is written with a lowercase letter (private), or you imported the package but are not using its name.

Solution: Check that all necessary functions are exported (with a capital letter), and that you are calling them