Your First Go Application

Every Go engineer starts with a single source file, but what you learn in that first project sets the tone for how you structure, build, and reason about software. Go is a compiled language with a deliberate focus on simplicity, and its toolchain reflects that: no hidden build scripts, no complex project generators—just a few commands and a clear mental model.

In this article you will create a small command‑line application from scratch. More importantly, you will understand the workflow that professional Go developers use every day: initialise a module, organise code, format it, run it, and compile it into a standalone executable.

Create a New Go Project

Start by creating a dedicated directory for your project. Go does not force you to put code in a specific workspace; a new project can live anywhere on your filesystem.

mkdir first-go-app
cd first-go-app

Giving every project its own directory keeps dependencies and build outputs isolated. It also makes it clear where a project begins and ends, a habit that pays off when you work on multiple services or libraries simultaneously.

Initialize a Go Module

A module is the fundamental unit of code distribution and dependency management in modern Go. It is defined by a go.mod file that sits at the root of your project.

go mod init first-go-app

This command creates a go.mod file containing the module path (first-go-app) and the Go version your project targets. The module path acts as the import prefix for all packages inside your project and, when you publish a library, as the identifier other developers use to import it.

Modules replaced the older GOPATH‑centric approach and are the only workflow actively maintained by the Go team. Every new project should start with go mod init.

Understand the Project Structure

After initialising the module, your directory looks like this:

first-go-app/
└── go.mod

go.mod is the single source of truth for your module’s identity and its external dependencies. You will add a source file next, and the layout will naturally grow from there.

Write Your First Go Program

Create a file named main.go with the following content:

package main

import "fmt"

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

Let's examine each part:

package main – defines the package this file belongs to. A program needs a main package with a main() function to produce an executable. Library packages use different names.
import "fmt" – brings the fmt package from the standard library into scope. fmt provides formatted I/O, and Println prints a line to standard output.
func main() – the entry point of the program. When you run the compiled binary, execution begins here.

This small program is already a complete, compilable Go application.

Run the Application

You can execute the program directly without manually compiling it first:

go run .

The go run command compiles the package in the current directory (the . argument) to a temporary binary and immediately executes it. You should see Hello, Go! printed in the terminal.

go run is ideal for development and quick experiments because it combines compilation and execution into a single step. For production deployments, you will want to build a persistent binary.

Build an Executable

Compile the program into a standalone file:

go build

This produces an executable named first-go-app (or first-go-app.exe on Windows) in the current directory. You can run it directly:

./first-go-app

The key differences between go run and go build:

Command	Purpose
`go run .`	Compile and run immediately; does not keep the binary.
`go build`	Compile and produce a reusable binary.

go build is what you use to create artifacts for testing, CI pipelines, and production deployments. The binary is statically linked by default, meaning it contains everything it needs and can be copied to another machine with the same operating system and architecture without installing Go.

Understanding the Go Development Workflow

Professional Go development follows a tight, repeatable loop:

Write code – edit .go files.
Format code – run gofmt or let your editor do it on save to enforce consistent style.
Run tests – execute go test ./... to verify behaviour.
Build and run – use go build or go run . to check the program.
Iterate – repeat the cycle.

The most essential commands you will use daily are:

go fmt ./...        # format all packages in the module
go test ./...       # run all tests
go build            # compile the current package
go run .            # compile and run the current package

Even in this first project, start the habit: after writing main.go, run go fmt ./... to ensure your code follows the standard formatting rules that every Go developer expects.

Common Beginner Mistakes

Small missteps can cause frustrating errors. Here are the most frequent ones and how to avoid them:

Forgetting package main – a program without a main package cannot produce an executable. The compiler will tell you package … is not a main package.
Incorrect imports – if you misspell "fmt" or import a package you never use, the compiler will refuse to build. Go treats unused imports as an error to keep code clean.
Missing main() function – the main package must declare func main() with no arguments and no return value. If it is absent, you will see runtime.main_main·f: function main is undeclared.
Running outside the module directory – commands like go run . and go build expect a module root that contains go.mod. If you are in a subdirectory without its own module, you must either specify the package path or run from the module root.
Manually editing go.mod – while it is plain text, go.mod is best managed through go mod commands (go mod tidy, go get). Manual edits can break the module graph.
Ignoring compiler errors – Go’s error messages are detailed and actionable. Read them carefully; they almost always point directly at the problem.
Forgetting to format – unformatted code stands out in code reviews and hinders readability. Run gofmt or configure your editor to do it on save.

If you hit a wall, start by reading the error message and checking your current working directory with pwd (or cd on Windows). Most early issues are environmental.

Best Practices

From day one, adopt habits that scale:

One module per project – a module corresponds to a deployable unit or a reusable library. Avoid nesting multiple go.mod files inside a single project unless you have a specific reason.
Use meaningful module paths – first-go-app is fine for learning. In production, use paths that reflect your repository (e.g. github.com/your-org/your-service).
Keep main.go simple – the entry point should wire dependencies together and start the application, not implement business logic. This separation will become clearer when you reach the Engineering section.
Format code with gofmt – consistent formatting eliminates style debates and lets you focus on logic. It is non‑negotiable in professional Go environments.
Read compiler errors carefully – Go’s toolchain is designed to provide clear, actionable feedback. Trust it.
Build frequently – compile often to catch mistakes early. The fast compiler makes this a seamless part of the workflow.

Go’s philosophy is that code should be simple, explicit, and easy to read. Every one of these practices reinforces that goal.

What You Have Learned

By building this small application, you have already touched the core of the Go development model:

Creating a self‑contained project directory
Initialising a Go module with go mod init
Writing a main package and a main() function
Importing and using a standard library package
Running code with go run
Compiling a standalone executable with go build
Applying gofmt to enforce idiomatic style
Following a professional development loop

This foundation is the launchpad for everything else in the handbook.

Next Steps

Now that you have a working Go project, deepen your understanding of the tools and language constructs that will power your daily engineering work:

Understanding Go Modules – learn dependency management, versioning, and how to structure multi‑package projects.
Go Foundations – dive into variables, types, functions, and the building blocks of every Go program.
Go Concurrency – when you are ready, explore goroutines and channels, the signature feature of Go.

Your first Go application is complete. The next step is to make it a habit.

Create a New Go Project​

Initialize a Go Module​

Understand the Project Structure​

Write Your First Go Program​

Run the Application​

Build an Executable​

Understanding the Go Development Workflow​

Common Beginner Mistakes​

Best Practices​

What You Have Learned​

Next Steps​