Your first Go program: go run and go build

A Go program of ten lines, built with one command, becomes a 2.3 MB file that runs on its own, and the same command builds it for Linux and Windows from a Mac. On the way you meet the three errors every newcomer sees first: an unused import, an unused variable and an opening brace on a line of its own.

You will write and run a main package, fix those three errors, let gofmt lay out the code and go vet check it, build an executable and read the build information it carries, and build the same program for two other systems.

A program starts in func main of package main

Every Go file begins with a package clause, and a program is the package named main. Here is a whole program:

// hello.go: a whole Go program. It starts in func main of package main.
package main

import "fmt"

func main() {
	name := "Asha"
	fmt.Println("Hello,", name)
	fmt.Printf("%s has %d letters\n", name, len(name))
}

Hello, Asha
Asha has 4 letters

Read it from the top. package main says this file belongs to the main packagepackage main: The package that makes a program. It must be named main and declare a func main that takes no arguments and returns nothing; running the program runs that function.. import "fmt" makes the standard formatting package available under the name fmt. func main() is where the program starts: the specification says a program runs by initializing it and then calling the function main of package main, which takes no arguments and returns no value, and the program ends when main returns. Inside it, name := "Asha" declares a variable and gives it a value at once, fmt.Println prints its arguments separated by spaces, and fmt.Printf fills %s with a string and %d with a whole number.

go run hello.go compiled that file and ran it; its output is under the code. Step through what the command did, and what changes when you run the same, unchanged file a second time:

go run is the command for writing and trying a program: it leaves no file beside your code. The program it built lives in a temporary folder while it runs, and a copy waits in the build cache for the next run.

Go refuses an unused import or an unused variable

Programs change while you write them, and a line you no longer need is easy to leave behind. Go does not let it stay. This file imports a package it never uses and declares a variable it never reads:

// unused.go: an import and a variable that are never used.
package main

import (
	"fmt"
	"os"
)

func main() {
	count := 3
	fmt.Println("Hello, Go")
}

# command-line-arguments
./unused.go:6:2: "os" imported and not used
./unused.go:10:2: declared and not used: count

The run failed before anything was built, with two errors: "os" imported and not used and declared and not used: count. The first comes from the specification itself, which makes it illegal to import a package without referring to anything it exports. The second is an implementation restriction: the specification allows a compiler to reject a variable declared inside a function body and never used, and the standard compiler does. An unused function, or an unused variable at package level, outside every function, compiles; only these two cases stop the build.

The blank identifierblank identifier: The name _ (an underscore), which takes a value and throws it away. It lets code ignore a result on purpose, or import a package only for what it does when it starts. _ is the deliberate way out. _ = count uses the value by throwing it away, and import _ "image/png" imports a package only for what it does when the program starts.

A line break can end a statement, so the brace stays on the line

Go source has no semicolons at the ends of lines, because the compiler inserts them. That rule, called semicolon insertionsemicolon insertion: Go's rule that a semicolon is added after a line whose last token could end a statement, such as a name, a literal or a closing bracket. It is why an opening brace must stay on the line before it., decides where an opening brace may go:

// brace.go: the opening brace on a line of its own.
package main

import "fmt"

func main()
{
	fmt.Println("Hello, Go")
}

# command-line-arguments
./brace.go:7:1: syntax error: unexpected semicolon or newline before {

The compiler stopped at line 7, column 1: syntax error: unexpected semicolon or newline before {. Step through what it did with the two lines:

The same rule holds for if, for, switch and select: Effective Go notes that the opening brace of a control structure cannot go on the next line, because a semicolon would be inserted before it. So there is no brace style to choose in Go, and the tool of the next section puts every brace where it belongs anyway. The rule is also why most Go lines have no semicolon at all: you write them only between the clauses of a for loop, as in for i := 0; i < 3; i++, or to put two statements on one line.

gofmt lays the code out, and go vet finds what compiles but is wrong

Go has one layout for source code, and a tool applies it. gofmtgofmt: The tool that lays out Go source in the one standard format, with tabs for indentation and spaces for alignment. gofmt -l lists the files it would change and gofmt -w rewrites them. indents with tabs, aligns with spaces, and puts every space and blank line where the standard format wants it, so layout never has to be discussed in a code review; go fmt ./... runs it on every package of a module. Here are two files: the first typed without care, the second laid out well but with a bug:

package main
import "fmt"
func main() {
    name:="Asha"
  if len(name)>3 {
        fmt.Println("Hello,",name)
  }
}

// vetme.go: it compiles, but the verb %d does not fit a string.
package main

import "fmt"

func main() {
	name := "Asha"
	fmt.Printf("Hello, %d\n", name)
}

from session import run

# gofmt lists, shows and fixes layout; go vet finds a bug the compiler accepts.
run(
    """
gofmt -l tidy
gofmt -d tidy/messy.go
gofmt -w tidy/messy.go
gofmt -l tidy
go vet tidy/vetme.go
go run tidy/vetme.go
""",
    expect_failure=["gofmt -d tidy/messy.go", "go vet tidy/vetme.go"],
)

$ gofmt -l tidy
tidy/messy.go
$ gofmt -d tidy/messy.go
diff tidy/messy.go.orig tidy/messy.go
--- tidy/messy.go.orig
+++ tidy/messy.go
@@ -1,8 +1,10 @@
 package main
+
 import "fmt"
+
 func main() {
-    name:="Asha"
-  if len(name)>3 {
-        fmt.Println("Hello,",name)
-  }
+	name := "Asha"
+	if len(name) > 3 {
+		fmt.Println("Hello,", name)
+	}
 }
[exit status 1]
$ gofmt -w tidy/messy.go
$ gofmt -l tidy
$ go vet tidy/vetme.go
tidy/vetme.go:8:21: fmt.Printf format %d has arg name of wrong type string
[exit status 1]
$ go run tidy/vetme.go
Hello, %!d(string=Asha)

gofmt -d ended with exit status 1 after showing its changes, which lets a script fail on unformatted code. The last two commands show why go vetgo vet: The go command that reports code which compiles but is probably wrong, such as a Printf verb that does not fit its argument. matters: vetme.go compiles, and it runs, but it prints Hello, %!d(string=Asha), because %d expects a number and got the string Asha. vet caught the mistake before the program ran: fmt.Printf format %d has arg name of wrong type string. Editors can run gofmt each time you save, and gopls reports static-analysis findings while you type.

go build writes one executable that records how it was built

go run keeps nothing beside your code. To get a file you can test, copy or ship, make the program a module and build it. The session makes a module named example.com/greeter from hello.go, builds it, runs the result and looks inside:

from session import run

# Make a module from hello.go, build it, run the binary and read what it carries.
run("""
mkdir greeter
cp hello.go greeter/main.go
cd greeter && go mod init example.com/greeter
cat greeter/go.mod
cd greeter && go build
ls greeter
./greeter/greeter
du -h greeter/greeter
go version -m greeter/greeter
file greeter/greeter
""")

$ mkdir greeter
$ cp hello.go greeter/main.go
$ cd greeter && go mod init example.com/greeter
go: creating new go.mod: module example.com/greeter
go: to add module requirements and sums:
	go mod tidy
$ cat greeter/go.mod
module example.com/greeter

go 1.27.1
$ cd greeter && go build
$ ls greeter
go.mod
greeter
main.go
$ ./greeter/greeter
Hello, Asha
Asha has 4 letters
$ du -h greeter/greeter
2.3M	greeter/greeter
$ go version -m greeter/greeter
greeter/greeter: go1.27.1
	path	example.com/greeter
	mod	example.com/greeter	(devel)	
	build	-buildmode=exe
	build	-compiler=gc
	build	CGO_ENABLED=1
	build	CGO_CFLAGS=
	build	CGO_CPPFLAGS=
	build	CGO_CXXFLAGS=
	build	CGO_LDFLAGS=
	build	GOARCH=arm64
	build	GOOS=darwin
	build	GOARM64=v8.0
$ file greeter/greeter
greeter/greeter: Mach-O 64-bit executable arm64

go mod init wrote a go.mod with the module path and the go line: Go 1.27.1 wrote go 1.27.1, its own version. go build printed nothing, which means it worked, and left an executable named after the last part of the module path, greeter. The file runs without the go command, and du measured it at 2.3 MB: the program’s own code is tiny, and the rest is the Go runtime and the packages it uses.

go version -m prints the build informationbuild information: What the go command records inside every executable it builds: the Go version, the module path and the build settings. go version -m prints it. that every Go executable carries:

Those lines are what you read when a binary misbehaves somewhere else: they say which release built it, for which system, and with which settings.

One computer builds for every system

GOOS and GOARCH choose the target of a build. Set them in front of go build and the same Mac builds for another operating system and processor; this is cross-compilingcross-compiling: Building a program on one system for another, such as a Linux or Windows executable on a Mac. In Go, the GOOS and GOARCH variables name the target system and processor., and Go needs nothing extra installed for it:

from session import run

# The same module, built on this Mac for Linux and for Windows.
run("""
mkdir greeter
cp hello.go greeter/main.go
cd greeter && go mod init example.com/greeter
cd greeter && GOOS=linux GOARCH=amd64 go build -o greeter-linux
cd greeter && GOOS=windows GOARCH=amd64 go build -o greeter.exe
file -b greeter/greeter-linux | cut -d, -f1-4
file -b greeter/greeter.exe
du -h greeter/greeter-linux greeter/greeter.exe
""")

$ mkdir greeter
$ cp hello.go greeter/main.go
$ cd greeter && go mod init example.com/greeter
go: creating new go.mod: module example.com/greeter
go: to add module requirements and sums:
	go mod tidy
$ cd greeter && GOOS=linux GOARCH=amd64 go build -o greeter-linux
$ cd greeter && GOOS=windows GOARCH=amd64 go build -o greeter.exe
$ file -b greeter/greeter-linux | cut -d, -f1-4
ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked
$ file -b greeter/greeter.exe
PE32+ executable (console) x86-64, for MS Windows
$ du -h greeter/greeter-linux greeter/greeter.exe
2.3M	greeter/greeter-linux
2.4M	greeter/greeter.exe

Step through the three builds of the two sessions:

file reported the Linux build as an ELF executable for x86-64, statically linkedstatically linked: An executable that holds every library it needs, so it runs on a machine where none of them is installed. Go's Linux executables are statically linked when cgo is not used.: it holds everything it needs and runs on a Linux server where Go was never installed. The cgo documentation says cgo is turned off by default when cross-compiling, which is why the Linux file needs no C library. The Windows build is a PE32+ console program of 2.4 MB. Each file runs only on the system it was built for: copy the Mac file to a Linux server and the kernel refuses to start it.

Practise: change, format, vet, build

Install Go first if you have not (the previous lesson), then work in a new folder:

1. Copy hello.go into it and run go run hello.go: it prints the two lines shown above.
2. Change main so that it prints a three-line receipt of your own, an item, a quantity and a price per line, using fmt.Printf with %s and %d.
3. Run gofmt -l . and go vet hello.go until both print nothing.
4. Run go mod init example.com/receipt, then go build, and start the program it wrote.
5. Run go version -m on the file and find its GOOS and GOARCH.

Then test the six ideas of this lesson. Each question comes with its explanation, and the weakest idea is asked first:

Interview questions

Warm-up (fresher): What is the difference between go run and go build?

go run compiles a main package, links it into an executable in a temporary folder and runs it at once, passing on any arguments after the package. Since Go 1.24 that executable is also kept in the build cache, so running unchanged code again skips the build, and by default go run leaves out the information debuggers use. go build compiles and links the same package but writes the executable beside your code, or to the file named by -o, and does not run it. Use go run while you write and try a program, and go build to make the file you test, copy or ship. Both build for the system named by GOOS and GOARCH, and only go build leaves a file you can copy to another machine.

Two longer interview questions of this module start from this lesson:

Key takeaways

• A program is the package main with a func main, and go run compiles it into a temporary executable, runs it and keeps a copy in the build cache for the next run.
• An unused import or an unused local variable stops the build; _ throws a value away on purpose, briefly.
• The compiler inserts a semicolon after a line that ends with ), so an opening brace must stay on the line that starts its block.
• gofmt gives every file the one standard layout, and go vet reports code that compiles but is probably wrong, such as a Printf verb that does not fit its argument.
• go mod init and go build turn the program into one executable, 2.3 MB here, whose build information go version -m prints.
• GOOS and GOARCH build the same code for other systems from one computer; the Linux build was statically linked.