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:
cd ~
curl -LO https://go.dev/dl/go1.27.4.linux-amd64.tar.gz
echo "7226736c2339719cda28fbf3a54d71aa63bcefe376e98cef00034268dab24840 go1.27.4.linux-amd64.tar.gz" | sha256sum -cOn 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:
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.gzNow ask Go which version you have:
go versionOn 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:
mkdir -p ~/hello-go
cd ~/hello-go
go mod init example.com/hello
cat go.modexample.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:
module example.com/hello
go 1.27.4The 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:
cd ~/hello-go
cat > main.go <<'GO'
package main
import "fmt"
func main() {
fmt.Println("Hello, world!")
}
GOYou 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 mainputs the file in the package calledmain. Go treatsmainas 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 themainfunction. When the program starts, Go runsmainin packagemain. 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 isPrintlnand notprintln.}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 asfunc main().
Run it:
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:
cd ~/hello-go
go build
ls -lh hello
./hello
go version -m hellogo buildwith no arguments builds the package in the current folder and names the binary after the last part of the module path:hello../helloruns it. The./is needed because the shell does not look in the current folder for commands.go version -m helloreads 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:
ldd helloldd 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:
cd ~/hello-go
GOOS=windows GOARCH=amd64 go build
ls -lh hello.exe
head -c 2 hello.exe; echoWriting 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:
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:
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)
}
GOThe new lines:
import ( ... )imports more than one package.flagis the standard library's command-line flag parser.name := flag.String("name", "world", "who to greet")defines a flag callednamewith the default valueworldand a help text.:=declares a new variable and works out its type from the right-hand side.flag.Stringreturns 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.%sis replaced by a string,\nis a newline (Printf, unlikePrintln, does not add one), and*namereads the string the pointer points to.
Run it with and without the flag:
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:
go run . -hCheck 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:
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 ./oopsThe 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:
cd ~/hello-go
printf 'package main\n\nfunc main() {\n\tcount := 3\n}\n' > oops/main.go
go run ./oopsGo 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:
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 oopsgofmt -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 givessyntax 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 withgo.mod file not found. Run Go commands from the folder that holdsgo.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:
cd ~
rm -rf ~/hello-goKeep 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
- Use the same toolchain to build something useful: write your first web server in Go, with routes, JSON and a clean shutdown, all from the standard library.
- Compare Go's single binary with another compiled language that also has a strict compiler: Hello World in Rust.
- See the compile and link stages Go hides from you: Hello World in C.
Related tutorials
- Hello World in Zig: zig run, zig build and zig ccYou will install a signature-checked Zig 0.17.1 on Ubuntu 26.04, write and run Hello World with the current I/O API, build a small project with zig build that handles errors explicitly, and use zig cc to compile a C program for Linux and for Windows.
- Hello World in x86-64 assembly with NASM and Linux system callsYou will write an x86-64 assembly program that prints a line using only Linux system calls, assemble it with NASM, link it with ld, check its exit status, then loop it three times and read its machine code with objdump.
- Hello World in WebAssembly text format with wabt and WasmtimeYou will write a WebAssembly module by hand in the text format, assemble it with wat2wasm, print Hello World through WASI in Wasmtime 50, and call an exported add function from both Wasmtime and Node.js.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials