Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Keywords and Statements

The package clause

Reference for the Go package clause: what it declares, why package main is special, naming rules, the blank package name, and how init functions run.

Every Go source file starts with a package clause: the keyword package followed by a name. All files in one directory that share the same package name form one package, and the compiler builds them together. The clause says which package a file belongs to, nothing more; it does not import anything and it does not create a namespace by itself.

The name main is special. A package called main that declares a function main() builds into an executable program. Any other name builds a library that other packages can import.

Go
package main

Try it

Go package main and package-level initialization

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Package-level names are visible everywhere in the package

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
package name
Part Description
name An identifier. Lowercase, short, no underscores or mixed caps by convention (strings, httputil). main marks an executable. The blank identifier _ is not allowed as a package name.

Rules and edge cases:

  • The package clause must be the first thing in the file other than comments.
  • All files in a directory must use the same package name. The only exception is test files, which may use name_test for black-box tests.
  • An executable needs package main and func main() with no parameters and no results. Missing main is the error function main is undeclared in the main package.
  • Identifiers that start with an uppercase letter are exported (usable from other packages). Lowercase ones are private to the package.

Usage notes

  • The package name is not the import path. The import path ("net/http") locates the package; the package clause (package http) gives the name used in code. They usually match the last path element, but they do not have to.
  • Choose names for the caller. Code reads strings.Join, so avoid repeating the package name in its contents (strings.StringJoin would stutter).
  • Avoid generic names such as util, common or helpers; they say nothing about what the package offers.
  • Initialization order: imported packages are initialized first. Then package-level variables are initialized in dependency order, and then every init() function in the package runs, files in the order the compiler receives them (the go tool sorts by file name). Finally main.main runs.
  • Several init functions are allowed in one package and even in one file. You cannot call them or take their address.
  • Import cycles are a compile error: package A cannot import B if B imports A, directly or indirectly.
  • Internal packages: a directory called internal can be imported only by code rooted at the parent of internal. This is enforced by the go tool.
  • On this site's runner every example is a single main.go, so each runnable example is package main.