When Does init() Run in Go? Package Initialization Explained

By the end of this page, you will understand when init() runs in Go, how package-level variables are initialized, how imported packages affect initialization order, and how all of this happens before main() starts. You will also see when init() matters outside of the main() package.

What init() is in Go

In Go, init() is a special function that is run automatically during package initialization.

You do not call it yourself.

func init() {
    // setup work
}

Go uses package initialization in a fixed sequence:

1. Initialize imported packages first
2. Evaluate package-level variable initializers
3. Run init() functions in that package
4. If this is the main package, run main()

What “variable declarations have evaluated their initializers” means

A package-level variable can be assigned a value when it is declared:

var port = readDefaultPort()
var appName = "My App"

These assigned expressions are called initializers.

• readDefaultPort() is an initializer expression
• "My App" is also an initializer expression

Think of Go program startup like opening a set of nested toolboxes.

• First, Go opens the toolboxes your package depends on
• Each toolbox sets up its own labels and tools first (package variables)
• Then it performs any automatic setup steps inside (init())
• Only when all required toolboxes are ready does Go open and run the main toolbox (main())

Another way to picture it:

• package variables = ingredients being prepared
• init() = kitchen setup after ingredients are ready
• main() = start cooking the actual meal

So init() does not prepare the raw ingredients themselves. It runs after those ingredients already exist.

Basic syntax

func init() {
    // runs automatically during package initialization
}

You can also have package-level variables:

var name = loadName()

Example: variable initializer, then init(), then main()

package main

import "fmt"

var message = createMessage()

func createMessage() string {
	fmt.Println("variable initializer runs")
	return "Hello"
}

func init() {
	fmt.Println("init runs")
}

func main() {
	fmt.Println("main runs:", message)
}

Output:

variable initializer runs
init runs
main runs: Hello

Traceable example

package main

import "fmt"

var a = first()
var b = second()

func first() string {
	fmt.Println("first initializer")
	return "A"
}

func second() string {
	fmt.Println("second initializer, sees a =", a)
	return "B"
}

func init() {
	fmt.Println("init, sees a =", a, "and b =", b)
}

func main() {
	fmt.Println("main, sees a =", a, "and b =", b)
}

Output:

first initializer
second initializer, sees a = A
init, sees a = A and b = B
main, sees a = A and b = B

Step by step

1. Go starts initializing the main package.
2. It evaluates package-level variables.
3. runs first.

Where init() is used in practice

Registering database drivers

Some packages register themselves during initialization.

import _ "github.com/lib/pq"

A blank import is often used specifically so that the imported package's init() runs and registers the driver.

Setting up package registries

A package might automatically register handlers, parsers, encoders, or plugins.

Validating configuration defaults

A package can compute default values before the rest of the program uses them.

Preparing lookup tables

If a package needs a precomputed map or table, it may build it during variable initialization or in init().

When not to use it

Avoid putting major application logic in init().

Examples of poor uses:

• opening database connections automatically
• starting servers
• performing network requests
• doing work that can fail in complex ways

Those actions are usually better handled explicitly from main() or a setup function.

Common patterns in real projects

1. Registration pattern

Packages often use init() to register themselves with a shared system.

func init() {
	registerFormat("json")
}

This is common in:

• database drivers
• image decoders
• plugin-like systems
• metrics exporters

2. Guarded setup of package state

A package may build internal state once during startup.

var supported = map[string]bool{
	"json": true,
	"xml":  true,
}

If the state can be created directly, package variables are often simpler than init().

3. Validation during startup

func init() {
	if defaultPort < 0 {
		panic("invalid defaultPort")
	}
}

1. Thinking init() is called manually

You never call init() yourself.

Broken idea:

func main() {
	init()
}

This is not how Go is meant to use init().

2. Thinking init() is only for the main package

Wrong assumption:

• init() runs only in the package containing main()

Correct idea:

• init() can run in any imported package

3. Doing too much work in init()

Broken style:

func init() {
	// expensive, hidden startup behavior
	fetchRemoteConfig()
	startBackgroundWorker()
}

init() vs other startup approaches

Package variables vs init()

Quick reference

Order of execution

1. Imported packages initialize first
2. Package-level variables are initialized
3. init() functions run
4. main() runs (only in package main)

What counts as an initializer?

var x = 10
var y = makeValue()
var name = "Go"

Each right-hand side is an initializer expression.

Rules for init()

• special function name: init
• no parameters
• no return values
• called automatically
• can exist in multiple files in the same package
• runs after package variables are initialized

Good uses

• registering drivers or handlers
• small setup for package internals
• validating fixed internal assumptions

Avoid using it for

• hidden network calls
• database connections with important runtime behavior
• long-running work
• major app orchestration

Basic example

var value = build()

func  {
	fmt.Println()
}

Does init() run before main() in Go?

Yes. In the main package, all package initialization completes before main() runs.

Does init() run before package-level variables?

No. Package-level variable initializers run first, then init() runs.

Can a package have more than one init() function?

Yes. A package may contain multiple init() functions, even across different files.

Does init() run in imported packages?

Yes. Imported packages are initialized before the package that imports them.

Can I call init() myself?

No. It is a special function managed by the Go runtime and compiler rules.

Is init() only useful in executable programs?

No. It is useful in any package that needs automatic initialization, especially registration-style packages.

Should I use init() for configuration and connections?

Usually only for small, predictable setup. For major configuration loading or opening connections, explicit startup code is often better.

Package initialization

This is the bigger lifecycle that includes imported packages, variable initialization, and init().

Package-level variables

These are initialized before init() and are central to understanding the startup order.

Import side effects

Blank imports often exist specifically so another package's init() runs.

main function

main() is the entry point of an executable, but it runs only after initialization is complete.

Blank identifier imports

Using _ in imports is closely related to packages that perform registration in init().

Go execution order

Understanding startup order helps explain why dependencies are ready before your code uses them.