Hello, World & Your First Module

Writing Hello World

Create a directory for your first program and put a single Go file in it:

mkdir -p ~/code/hello
cd ~/code/hello
touch main.go

Open main.go in your editor and type:

package main

import "fmt"

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

Seven lines of code. We'll unpack each one.

Line by line

package main

Every Go source file begins with a package declaration. The package main is special: it's the one Go recognizes as a runnable program. Any other package name (e.g. mathutil) would produce a library, not a binary. We'll revisit packages in depth in Chapter 18.

import "fmt"

import pulls in another package so you can use its exported names. fmt is Go's standard library package for formatted I/O: printing, string formatting, scanning input. You'll see fmt in almost every program.

func main() { … }

The entry point. Exactly one main function must live in the main package. When Go launches your binary, main() runs and, when it returns, the program exits.

fmt.Println("Hello, World!")

fmt.Println prints its arguments to standard output, separated by spaces, followed by a newline. The string "Hello, World!" is a Go string literal (Chapter 7 is dedicated to strings).

What's absent

Notice what's not there:

• No semicolons ending lines. Go inserts them automatically.
• No explicit types on anything. Go can tell "Hello, World!" is a string.
• No exception handling syntax. Errors in Go are values, returned from functions (Chapter 23).

Running it with go run

The quickest way to see output:

go run main.go

You should see:

Hello, World!

go run compiles your code to a temporary binary, executes it, then deletes the binary. It's perfect for iteration, no artifacts left behind.

You can also pass a directory or a package path:

go run .          # compile + run the current package
go run ./cmd/app  # compile + run a package at a relative path

Once your program has more than one file, you'll use go run . rather than listing individual files.

Your first module

Go projects are organized into modules. A module is just a directory with a go.mod file in it. Even for a one-file hello-world, it's good practice to initialize one:

go mod init example.com/hello

This creates a file called go.mod:

module example.com/hello

go 1.22

The module line declares the module's import path. It's typically a URL where the code lives (like github.com/you/hello) , even if you never publish it. The go line records the minimum Go version this module supports. You rarely edit go.mod by hand; Go tools do it when you add dependencies.

Building a binary with go build

To produce an actual executable file:

go build .

Go compiles your package and places the binary in the current directory. On macOS/Linux it's called hello; on Windows hello.exe. Run it:

./hello            # macOS / Linux
hello.exe          # Windows

You can also name the output file:

go build -o greet .
./greet

This binary is static: it has no external runtime dependencies. Copy it to a machine with the same OS/architecture and it runs. That's the Go deployment superpower in a nutshell.

go run vs build vs install

Typical example of go install:

# Install golangci-lint from the internet, now available on your $PATH
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

This is how you install most Go CLI tools. Make sure ~/go/bin is on your PATH (you set this up in Chapter 3).

Formatting with go fmt

Go has one canonical code style, enforced by the gofmt tool. No tabs-vs-spaces debates, no bikeshedding over where to put braces. Your editor should format on save (Chapter 3) , but you can also run it manually:

go fmt ./...

(The ./... pattern means "the current directory and all subdirectories recursively", a common Go idiom.)

An even better version is goimports, which runs gofmt and manages the import block for you:

go install golang.org/x/tools/cmd/goimports@latest
goimports -w .

Exit codes

Every program that finishes reports an exit code to its parent (usually the shell). 0 means success; anything non-zero means something went wrong. Go's main function returns 0 implicitly. To exit with a specific code:

package main

import (
    "fmt"
    "os"
)

func main() {
    if len(os.Args) < 2 {
        fmt.Fprintln(os.Stderr, "usage: greet NAME")
        os.Exit(1) // exit code 1, "usage error"
    }
    fmt.Println("Hello,", os.Args[1])
}

Two new ideas:

• os.Args is a slice containing the program name followed by command-line arguments. (We'll cover slices in Chapter 13.)
• fmt.Fprintln(os.Stderr, ...) writes to standard error instead of standard output, the Unix-conventional channel for errors.

Check the exit code after running:

go run .          # prints usage, exits 1
echo $?           # prints: 1
go run . Alice    # prints "Hello, Alice"
echo $?           # prints: 0

Cross-compilation

Go can build binaries for other operating systems and CPU architectures from your current machine. Two environment variables control this: GOOS and GOARCH.

# From a Mac, build a Linux binary
GOOS=linux  GOARCH=amd64  go build -o hello-linux   .

# ...a Windows binary
GOOS=windows GOARCH=amd64 go build -o hello.exe      .

# ...a Raspberry Pi (ARM) binary
GOOS=linux  GOARCH=arm64  go build -o hello-pi      .

See the full list with:

go tool dist list

This is why Go has become the go-to language for shipping CLI tools and cloud-native infrastructure: one developer, on one laptop, can produce binaries for every platform the tool needs to run on, no Docker or cross-toolchain setup required.

Check your understanding

Practice exercises

package main

import (
    "fmt"
    "os"
    "strings"
)

func main() {
    names := os.Args[1:]
    switch len(names) {
    case 0:
        fmt.Println("Hello, World!")
    case 1:
        fmt.Printf("Hello, %s!\n", names[0])
    default:
        fmt.Printf("Hello, %s!\n", strings.Join(names, " and "))
    }
}

go build -o greet .
./greet Alice

GOOS=linux GOARCH=amd64 go build -o greet-linux .
file greet-linux    # should say: ELF 64-bit LSB executable