LearnAI ToolsCareerPractice BuildsPlayContact
Lesson 615 min read

Your First Go Program

Write, run, and build your first Go program, and understand the difference between go run and go build.

Introduction

With Go installed, it's time to write actual code. In this lesson you'll create a small project from scratch, write a classic "Hello, World!" program, and learn the two main ways to execute Go code: `go run` for quick iteration, and `go build` for producing a distributable binary.

Setting Up the Project

Start by creating a new folder for your project and initializing it as a Go module, exactly as you learned in the previous lesson.

mkdir hello-go
cd hello-go
go mod init example.com/hello-go
Output

Click Run to see what this code prints.

Writing Hello World

Create a file named `main.go` inside that folder with the following contents.

main.go
package main


import "fmt"


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

Understanding package main

Every Go file starts with a package declaration. `package main` is special: it tells the Go compiler that this package should produce a standalone, runnable executable rather than a reusable library. Any other package name (like `package utils`) instead produces code meant to be imported by other packages, not run directly.

Understanding func main

Inside a `package main` file, the function named `main` is the program's entry point — it is the first (and only automatically invoked) function that runs when your compiled program starts. It takes no arguments and returns no value.

Requirements for a Runnable Program
  • The file must declare `package main` at the top.
  • It must define exactly one `func main()` function within that package.
  • Without both of these, `go run` and `go build` will fail with a compile error.

Running with go run

`go run` compiles your program to a temporary location and immediately executes it, then discards the compiled binary. It's the fastest way to try out code while developing.

go run main.go
Output

Click Run to see what this code prints.

Building with go build

`go build` compiles your program into a standalone executable file saved in your current directory, without running it. This is what you use when you want a distributable binary — for example, to deploy to a server or hand to a teammate who doesn't have Go installed.

go build
./hello-go        # macOS/Linux
hello-go.exe      # Windows
Output

Click Run to see what this code prints.

Notice that the resulting binary (`hello-go` or `hello-go.exe`) runs entirely on its own — it does not need Go installed on the machine that runs it, since everything it needs is compiled directly into the file.

go run vs go build

CommandWhat It DoesBest For
go run main.goCompiles to a temp file, runs it, then discards itFast iteration while developing
go buildCompiles to a permanent executable in the current directoryProducing a binary to distribute or deploy

Common Mistakes

Avoid These Mistakes
  • Forgetting `package main` or `func main()`, which produces a "runtime.main_main·f: function main is undeclared" or similar build error.
  • Trying to run a .go file that isn't part of an initialized module (missing `go.mod`).
  • Assuming `go build` runs the program automatically — it only compiles; you still need to execute the resulting binary yourself.
  • Committing the compiled binary produced by `go build` into version control — it should typically be excluded via .gitignore.

Best Practices

  • Use `go run` while actively writing and testing code for fast feedback.
  • Use `go build` (or `go install`) only when you need a distributable binary.
  • Name your entry-point file `main.go` by convention, even though Go doesn't strictly require that name.
  • Add compiled binaries to `.gitignore` so they don't get committed alongside your source code.

Frequently Asked Questions

No — Go doesn't require any specific file name. `main.go` is just a strong, widely followed convention for the file containing func main.

Not within the same package — a package can only have one func main(). Larger programs typically split code across multiple packages, with only one package main tying everything together.

On Windows it produces an .exe file; on macOS and Linux it produces an executable file with no extension, named after your module by default.

Key Takeaways

  • Every runnable Go program needs `package main` and a `func main()` entry point.
  • `go run` compiles and immediately executes code, discarding the binary afterward — great for fast iteration.
  • `go build` produces a standalone, distributable executable without running it.
  • Compiled Go binaries need no external runtime to execute.

Summary

You've now written, run, and built your first real Go program, and understand exactly what package main and func main do. Next, you'll look more closely at how Go files and packages are structured, and the rule that determines what code is visible outside a package.

Next Lesson →

Program Structure & Packages