Skip to main content

Hello World (first programs) · Beginner · 15 min

Hello World in Go: go mod init, go run and a single binary

By Padding · Updated 18 Nov 2026
Ubuntu 26.04 · Go 1.27.4 · golang:1.27 image (Debian 13)

You will install Go 1.27, create a module, run Hello World with go run, build it into one self-contained binary, cross-compile a Windows .exe from Linux and add a --name flag with the flag package.

On this page

Go is the language behind a large share of the tools that run servers today: Docker, Kubernetes, Terraform, Prometheus and Caddy are all written in it. It is also common for network services, APIs and command-line tools. The reason is mostly practical. Go compiles your code to one native binary with no runtime to install, it can build that binary for another operating system from your own machine, and its standard library already includes an HTTP server, JSON, testing and command-line flags.

Go also has opinions it enforces for you. An import you do not use, or a variable you declare and never read, stops the build. There is one official code layout, and the gofmt tool applies it, so Go teams do not argue about indentation. You will meet both rules in this tutorial.

You work in a throwaway folder, ~/hello-go, and delete it at the end.

Step 1 · Install Go 1.27.4

The Go team publishes Go as a tarball. Ubuntu's own golang package usually lags behind the current release, so install the official one. The download is about 70 MB; if you are on metered or prepaid mobile data, start it on Wi-Fi.

Download the archive and check it against the SHA-256 checksum listed on go.dev/dl, so you know the file arrived complete and unchanged:

Bash
cd ~
curl -LO https://go.dev/dl/go1.27.4.linux-amd64.tar.gz
echo "7226736c2339719cda28fbf3a54d71aa63bcefe376e98cef00034268dab24840  go1.27.4.linux-amd64.tar.gz" | sha256sum -c

On an ARM machine (a Raspberry Pi 4 or 5, or an ARM cloud server) use go1.27.4.linux-arm64.tar.gz and the checksum shown for it on go.dev/dl.

The next command deletes any existing /usr/local/go before unpacking. That is what you want if an older Go lives there, but check first with ls /usr/local/go if you are not sure what it holds. Then unpack, and add Go's bin folder to your PATH:

Bash
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.27.4.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile
source ~/.profile
rm go1.27.4.linux-amd64.tar.gz

Now ask Go which version you have:

Bash
go version

On Windows and macOS, download the .msi or .pkg installer from go.dev/dl and run it; it sets up PATH for you. Open a new terminal afterwards so the change is picked up. WSL users follow the Ubuntu commands.

A Go installed from a tarball gets no updates from apt. To upgrade later, repeat the same commands with the new version number from go.dev/dl.

Check it worked

go version prints go version go1.27.4 linux/amd64 (or linux/arm64, windows/amd64, darwin/arm64 on other machines). If you see go: command not found, the PATH line has not been loaded yet; open a new terminal or run source ~/.profile again.

Step 2 · Create a module with go mod init

Every Go program lives in a module: a folder with a go.mod file that gives the code a name and records which Go version and which libraries it needs. Make the folder and create the module:

Bash
mkdir -p ~/hello-go
cd ~/hello-go
go mod init example.com/hello
cat go.mod

example.com/hello is the module path. For code you will publish it is usually where the code lives, such as github.com/yourname/hello. For a local program any name in that shape works.

Check it worked

go mod init prints go: creating new go.mod: module example.com/hello, and cat go.mod shows two lines:

Text
module example.com/hello

go 1.27.4

The go line records the Go version the module was written for, taken from the toolchain that ran go mod init. Anyone building the module needs at least that version; with the default settings, an older go command (1.21 or later) downloads a newer toolchain before it builds.

Step 3 · Write main.go and run it with go run

Create the source file:

Bash
cd ~/hello-go
cat > main.go <<'GO'
package main

import "fmt"

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

You can type the same seven lines into an editor and save them as main.go in ~/hello-go. Here is what each line does:

  • package main puts the file in the package called main. Go treats main as special: it is the one package that builds into a program you can run. Any other name builds a library.
  • import "fmt" brings in the standard library's formatting package, which prints text.
  • func main() { starts the main function. When the program starts, Go runs main in package main. It takes no arguments and returns nothing.
  • fmt.Println("Hello, world!") prints the text and then a newline. Exported names from another package start with a capital letter, which is why it is Println and not println.
  • } closes the function. There are no semicolons: the compiler adds them at line ends for you, which is also why the { must sit on the same line as func main().

Run it:

Bash
cd ~/hello-go
go run .

The . means "the package in this folder". go run compiles the program into a temporary folder, runs it and throws the binary away. It is the quick loop for trying things.

Check it worked

The terminal prints Hello, world!. If you see go: go.mod file not found in current directory or any parent directory, you are not inside ~/hello-go; run cd ~/hello-go and try again.

Step 4 · Build one binary with go build

go run keeps nothing. go build writes a program you keep, copy and ship:

Bash
cd ~/hello-go
go build
ls -lh hello
./hello
go version -m hello
  • go build with no arguments builds the package in the current folder and names the binary after the last part of the module path: hello.
  • ./hello runs it. The ./ is needed because the shell does not look in the current folder for commands.
  • go version -m hello reads the build information Go stores inside every binary: the Go version that built it and the module path.

Now see what the binary needs from the system to run:

Bash
ldd hello

ldd replies not a dynamic executable. A C program from the same machine would list libc.so.6 and other shared libraries; this one lists none, because Go linked everything it needs into the file. Programs that use certain parts of the standard library through C (some networking and user lookups) can link against the C library, but a program like this one is fully static.

That is the main reason operations teams like Go. To run hello on another Linux server with the same processor type, copy the one file across. There is no runtime, interpreter or package to install first, and nothing to keep in step with the server's own libraries.

Check it worked

ls -lh shows a file called hello of roughly 2 MB. ./hello prints Hello, world!. go version -m hello starts with hello: go1.27.4 and lists path example.com/hello. ldd hello prints not a dynamic executable.

Step 5 · Cross-compile a Windows .exe

Go can build for another operating system and processor without installing anything extra. Two environment variables pick the target: GOOS (the operating system) and GOARCH (the processor). Build a Windows version from Linux:

Bash
cd ~/hello-go
GOOS=windows GOARCH=amd64 go build
ls -lh hello.exe
head -c 2 hello.exe; echo

Writing GOOS=windows GOARCH=amd64 in front of the command sets those variables for that one command only. Your next plain go build builds for Linux again.

head -c 2 prints the first two bytes of the file. Every Windows program starts with the letters MZ, so this proves you made a Windows file and not a Linux one. Copy hello.exe to a Windows PC, open a terminal in its folder and run .\hello.exe to see the greeting.

Go lists every target it can build for:

Bash
go tool dist list | grep -E '^(windows|darwin|android)/'

Swap in GOOS=darwin GOARCH=arm64 for an Apple-silicon Mac, or GOOS=linux GOARCH=arm64 for an ARM server or a Raspberry Pi.

Check it worked

ls -lh hello.exe shows the Windows binary next to the Linux one, and head -c 2 prints MZ. The target list includes windows/amd64, darwin/arm64 and android/arm64.

Step 6 · Add a --name flag with the flag package

Now let the reader of your program choose who to greet. Replace main.go with this version:

Bash
cd ~/hello-go
cat > main.go <<'GO'
package main

import (
	"flag"
	"fmt"
)

func main() {
	name := flag.String("name", "world", "who to greet")
	flag.Parse()
	fmt.Printf("Hello, %s!\n", *name)
}
GO

The new lines:

  • import ( ... ) imports more than one package. flag is the standard library's command-line flag parser.
  • name := flag.String("name", "world", "who to greet") defines a flag called name with the default value world and a help text. := declares a new variable and works out its type from the right-hand side.
  • flag.String returns a pointer to a string, not the string itself, because the value is only known after the flags are parsed.
  • flag.Parse() reads the command-line arguments and fills in the flag values. Call it once, after you have defined every flag.
  • fmt.Printf("Hello, %s!\n", *name) prints formatted text. %s is replaced by a string, \n is a newline (Printf, unlike Println, does not add one), and *name reads the string the pointer points to.

Run it with and without the flag:

Bash
cd ~/hello-go
go run .
go run . --name Ada
go run . -name=Adébáyọ̀

The flag package accepts one dash or two, and a space or = between flag and value. Go strings are UTF-8, so names in Yoruba, Amharic or Arabic script print correctly with no extra work. One catch: len("Adébáyọ̀") is 13, because len() counts bytes, not letters. The name has 7 letters, and utf8.RuneCountInString counts 8 runes (Unicode code points), because the tone mark on ọ̀ is a separate combining character.

Ask for the help text the flag package writes for you:

Bash
go run . -h

Check it worked

The three runs print Hello, world!, Hello, Ada! and Hello, Adébáyọ̀!. go run . -h prints a usage line followed by -name string and who to greet (default "world"). Run go build again and ./hello --name Ada gives the same greeting from the binary.

Step 7 · Let the compiler and gofmt catch mistakes

Make Go's strictest rules fail on purpose, so you recognise the messages when they happen by accident. Work in a scratch folder inside the module so main.go stays intact.

An unused import. Most compilers warn about this. Go refuses to build:

Bash
cd ~/hello-go
mkdir -p oops
printf 'package main\n\nimport (\n\t"fmt"\n\t"os"\n)\n\nfunc main() {\n\tfmt.Println("hi")\n}\n' > oops/main.go
go run ./oops

The error reads something like oops/main.go:5:2: "os" imported and not used. The numbers are the line and column. Delete the import, or use it.

An unused variable. Same rule for variables declared inside a function:

Bash
cd ~/hello-go
printf 'package main\n\nfunc main() {\n\tcount := 3\n}\n' > oops/main.go
go run ./oops

Go reports declared and not used: count. While you are experimenting, _ = count tells the compiler you mean to ignore it.

Formatting. Write a valid but untidy file, then let gofmt fix it:

Bash
cd ~/hello-go
printf 'package main\nimport "fmt"\nfunc main(){\nfmt.Println( "tidy" )}\n' > oops/main.go
gofmt -l oops
gofmt -w oops
cat oops/main.go
gofmt -l oops

gofmt -l lists files whose layout differs from the standard, -w rewrites them in place, and the second -l prints nothing because the file is now formatted. Most editors with Go support run gofmt on every save, so you rarely call it yourself; go fmt ./... does the same for a whole module.

Two more mistakes beginners make:

  • Opening brace on its own line. func main() followed by { on the next line gives syntax error: unexpected semicolon or newline before {, because Go added a semicolon at the end of the first line.
  • Running outside the module. go run . from your home folder fails with go.mod file not found. Run Go commands from the folder that holds go.mod, or a folder below it.

Check it worked

You saw "os" imported and not used and declared and not used: count in your own terminal, and neither program ran. After gofmt -w, cat oops/main.go shows the code indented with tabs and the function body on its own lines, and gofmt -l oops prints nothing.

Step 8 · Clean up

Delete the demo folder and everything in it:

Bash
cd ~
rm -rf ~/hello-go

Keep Go installed if you are carrying on with the next tutorial. To remove it, run sudo rm -rf /usr/local/go and delete the export PATH line you added to ~/.profile. Go also keeps a build cache; go clean -cache empties it before you remove Go.

Check it worked

ls ~/hello-go reports No such file or directory.

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.