Packages, imports and visibility
A package is a folder of Go files that share one namespace. Every file of the folder starts with the same package line, and the folder's name is the last element of its import path. A package decides what the rest of the program may use: a name that starts with a capital letter is exported, everything else is private to the package.
One folder, one package
This small module has three packages: main at the root, money and price. Each of them is a folder with one or more files that begin with the same package name. Go has no header files and no forward declarations: the compiler reads the whole package, and the order of files and functions does not matter.
package money
// Amount is a number of cents. It is a named type, so a plain int does not
// pass for it by accident.
type Amount int64
// FromCents builds an Amount from a number of cents.
func FromCents(cents int64) Amount {
return Amount(cents)
}
// Float64 returns the amount as a number of units.
func (a Amount) Float64() float64 {
return float64(a) / 100
}
Amount is a named type over int64, which makes the compiler refuse a bare integer where an amount is expected. FromCents is the constructor, and Float64 is the method that turns the amount into a number of units. All three names are exported, so other packages can use them.
package price
import "example.com/shop/money"
// Price is an amount in a currency. The fields are exported so that other
// packages can read them, and the methods are the way to compute with it.
type Price struct {
Amount money.Amount
Currency string
}
// Net returns the amount as a floating point number of units.
func (p Price) Net() float64 {
return p.Amount.Float64()
}
The price package imports money and uses its exported names. It is a different package, so it can only see Amount, FromCents and Float64; a lowercase helper of money would be invisible here.
Imports
The main package imports the standard library first, a blank line, then the module's own packages. That grouping is a convention of gofmt, not a rule of the compiler, and goimports (a tool outside the standard distribution) maintains it automatically. An import path that the module does not provide is a build error, and the message names the path.
package main
import (
"fmt"
"example.com/shop/money"
"example.com/shop/price"
)
func main() {
p := price.Price{Amount: money.FromCents(1999), Currency: "EUR"}
fmt.Println(p)
fmt.Printf("%.2f %s before tax\n", p.Net(), p.Currency)
}
go run .
go vet ./...
go build -o shop .
./shop
{1999 EUR}
19.99 EUR before tax
{1999 EUR}
19.99 EUR before tax
The import path is not a file path: example.com/shop/money is resolved inside the module declared in go.mod, and the folder it names is money. A package is imported by path and used by its package name, which is why the calls read money.FromCents.
Visibility and its error
The rule is one character: a name that begins with a capital letter is exported, and everything else is private to its package. There is no public keyword, no friend declaration and no way to reach a private name from outside. The program below uses a private function of another package, and the compiler says exactly that.
package main
import (
"fmt"
"example.com/shop/money"
)
func main() {
fmt.Println(money.fromCents(1999))
}
go build -o shop .
# example.com/shop
./main.go:10:20: undefined: money.fromCents (but have FromCents)
The same rule applies to fields of a struct and to methods, which is what makes an unexported field the way to keep an invariant: a package can hand out a struct with private fields and exported methods, and no caller can put it into an invalid state. The lesson on structs uses this for its first type with a constructor.
Exercises
- Add an unexported function to the money package and call it from a second exported function. Does the main package need to change?
- Rename the folder money to cash and leave the package name alone. Which lines of the program must change, and which may stay?
- Give Price an unexported field tax and a constructor that sets it. Can another package create a Price with a tax of its own?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What makes a name visible outside its package?
Answer
It starts with a capital letter
Go's visibility rule is the case of the first letter, and nothing else.
-
What is the package name of the folder money in the module example.com/shop?
Answer
money, as the first line of its files declares
The package clause names the package; by convention it matches the folder.
-
What is the import path of that package?
Answer
example.com/shop/money
The import path is the module path plus the folder path inside the module.
-
How many packages can one folder hold?
Answer
One
All files of a folder declare the same package, except test files of the package_test form.
-
What does the compiler say about
money.fromCents(1999)from another package?Answer
undefined: money.fromCents
The name does not exist for the importing package, and the compiler reports it as undefined.
-
What does this program print?
package main import ( "fmt" "strings" ) func main() { fmt.Println(strings.ToUpper("go")) }Answer
GO
ToUpper returns an uppercase copy, and the package is used, so the program builds.
-
Why does Go not need header files?
Answer
The compiler reads the whole package from its sources
Package-level compilation removes the declaration/definition split of C and C++.
-
What is the constructor of a named type in Go?
Answer
An ordinary function that returns the type
There are no constructors in the language; a function such as FromCents returns a valid value.
-
What does an unexported struct field give a package?
Answer
The ability to keep an invariant, because no other package can write it
Private fields can only be changed by the package that owns them, through its methods.
-
Which line of a file must come first?
Answer
The package clause
Every file begins with package name; imports and declarations follow.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev