Install Go, create a directory, initialize a module, add a package main program, and run go run .. The essential sequence is:
mkdir hello-go && cd hello-gogo mod init example.com/yourname/hello-go- Create
main.gowith amainfunction. go run .
A normal Go project is one module (identified by go.mod) containing one or more packages. Use go work only when you deliberately develop multiple modules together.
Prerequisites and the recommended starting shape
You need an installed Go toolchain, a text editor, and a terminal. The official Go tutorial lists VS Code, GoLand, and Vim as editors with Go support (Go getting-started tutorial). Verify the installation before creating a project:
go versionIf the command is not found, install Go from the official distribution for your operating system, reopen the terminal, and run the version check again. Keep the project in a directory managed by your source-control system. A repository-shaped module path is the maintainable default when code will be published or shared.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems#1 Best Overall
Step 1: Create a directory and initialize a module
-
Create and enter the project directory
mkdir hello-go cd hello-go -
Initialize
go.modgo mod init example.com/yourname/hello-goReplace the example path with the repository or module path you will use. The command writes a new
go.modin the current directory, making that directory the module root. The Go Modules Reference describesgo mod initas creating a module rooted at the current directory (Go Modules Reference).
A newly created file is typically similar to:
module example.com/yourname/hello-go
go 1.XXThe module line is the import path for this module. The go line records the language/toolchain compatibility declared by the module. Let the installed Go command write the appropriate version rather than copying a version from an unrelated example. Dependency requirements will appear as additional require entries after you add imports and tidy the module.
Step 2: Write and run the first program
Create main.go
At the module root, create this file:
package main
import "fmt"
func main() {
fmt.Println("Hello, World!")
}Executable commands must use package main, and main is the entry point (Go code guide). A package can contain several .go files, but files in the same directory normally belong to the same package and are compiled together.
Run from the module root
go run .The command builds and runs the main package in the current module for this invocation. You should see Hello, World!. The dot matters: it tells Go to use the package in the current directory. You can also run a named file for a quick experiment, but go run . exercises the module-shaped project you will keep.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Understand the project layout
A small command may begin with only:
hello-go/
├── go.mod
└── main.goAs the program grows, split cohesive functionality into packages and directories rather than putting every type in main.go. A common arrangement is:
hello-go/
├── go.mod
├── go.sum
├── cmd/
│ └── hello/
│ └── main.go
├── internal/
│ └── greeting/
│ └── greeting.go
└── README.mdThis is a convention, not a requirement. Go discovers packages from directories; there is no project-file list to maintain. Keep go.mod at the root that owns the import path. Use internal when a package should only be imported by code inside its parent tree. If you publish a reusable library, give it a stable module path and document its package API; if you are building one command, a root main.go is perfectly valid.
Add dependencies safely
Import a package, then tidy
When source code imports a third-party module, run:
go mod tidygo mod tidy makes go.mod match the packages actually imported by the module and updates go.sum with checksums for selected dependencies (Go Modules Reference). Commit both files when the project is under version control. Review the resulting changes instead of adding arbitrary versions by hand.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallUse explicit dependency commands when needed
For a dependency you intentionally want to add or upgrade, use the Go command (for example, go get module/path@version), then run go mod tidy. Keep application and library code importing the module path declared by its author. If a package was moved, update imports and tidy again so stale requirements are removed.
Test before the project gets large
Write a test file
Test files end in _test.go. For example, add greeting_test.go beside a package’s source:
package greeting
import "testing"
func TestMessage(t *testing.T) {
got := Message("Go")
want := "Hello, Go!"
if got != want {
t.Fatalf("Message() = %q, want %q", got, want)
}
}The test uses Go’s built-in testing package. A matching implementation might be:
package greeting
func Message(name string) string {
return "Hello, " + name + "!"
}Run tests at the right scope
go testtests the package in the current directory.go test ./...recursively tests all packages in the module, which is a useful pre-commit check.go test -run TestMessagenarrows a run while diagnosing one test.
The _test.go naming rule and go test workflow are described in the official testing tutorial (Add a test) and the Go Modules wiki (Modules).
Recommended Free Tools
Format, build, and install
Format source consistently
gofmt -w .Run it on changed Go files (or use your editor’s format-on-save integration). Formatting is deterministic, so avoid mixing hand formatting with generated output.
Compile without installing
go build
go build ./...go build checks and compiles the package in the current directory. The recursive form checks every package in the module. Build a named command from a repository containing several commands with a package path such as go build ./cmd/hello.
Build and install a command
go install ./cmd/hellogo install builds a command and places the executable in the configured Go binary directory. Ensure that directory is on your shell’s PATH if you want to invoke the command by name. The distinction between building and installing is covered in the Go code guide (Go code).
When to use a Go workspace
Do not create a workspace merely because a project has several packages. A single module and its go.mod already manage normal package and dependency relationships.
Use go.work for multiple modules developed together
A workspace is useful when one repository contains independent modules that need to use each other’s local, unpublished changes. From the repository directory, initialize it with the modules you want to coordinate:
go work init ./module-a ./module-bThis creates go.work. You can initialize with one module and add another later. Commands run in the workspace resolve the listed modules together, while each module retains its own go.mod and can be versioned independently. The official workspace tutorial documents this flow (Workspaces).
Rank #4
| Situation | Use | Why |
|---|---|---|
| One application or library | One go.mod |
Simplest dependency and release model |
| Several packages in that application | Directories within the same module | Packages share one module definition |
| Several independently versioned modules needing local changes together | go.work |
Coordinates modules without publishing every intermediate version |
Commit a workspace file when it represents the repository’s intended development setup. For a personal local experiment, you may keep a temporary workspace configuration out of version control.
Common errors and fixes
go: cannot find main module
You ran a module-aware command outside a directory containing go.mod. Change into the module root, or initialize the directory with go mod init if it is a new project.
Free tools Windows power users keep installed
One-click scans. No signup required.
package command-line-arguments is not a main package
The files you are running do not declare package main, or they do not provide func main(). Library packages should not be run directly; create a command package with both.
no required module provides package ...
Check the import path for spelling and case, confirm that the dependency is available, then run go get for the intended module followed by go mod tidy. If the import is one of your own packages, verify that it begins with your module path and that the directory exists.
Missing or stale go.sum entries
Run go mod tidy from the module root. Do not delete checksum lines selectively to silence an error; identify whether an import or version requirement is obsolete.
Tests are not discovered
Confirm the filename ends exactly in _test.go, the test function starts with Test and has the signature accepted by the testing package, and that you are running the command in the package or module you intended.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Best Value
Workspace changes are ignored
Run commands from the directory containing go.work, inspect the file’s listed module directories, and check that each path contains a valid go.mod. A workspace does not merge modules permanently; it only changes local module selection while active.
Reliable day-to-day workflow
- From the module root, run
gofmton changed files. - Run
go test ./...to cover every package. - Run
go mod tidyafter import or dependency changes, then reviewgo.modandgo.sum. - Run
go build ./...to catch compilation errors across commands and libraries. - Use
go run .for local execution, andgo installonly when you need a command placed in your Go binary directory.
These commands are local and deterministic with respect to the selected toolchain and module versions. For reproducible automation, keep module files under version control and run the same test and build commands in continuous integration. A workspace can simplify coordinated development, but it also adds another module-selection file that contributors and CI must understand.
Or skip the browser setup
If you need screenshots of a Go documentation site, demo, or generated web output, ScreenshotNeo can capture a URL without maintaining browser automation. Its API accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers.
One request returns PNG, JPEG, WebP, or PDF. The API also supports full-page lazy-image loading, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and page options, custom CSS and JavaScript, pre-capture clicks, selector hiding, selector/delay/network-idle waits, request and resource blocking, custom headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, TTL-based caching, signed public-image links, asynchronous signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
For example, this cURL call captures the Go homepage as a WebP file:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://go.dev -o shot.webpSee the parameter reference and runnable examples in the ScreenshotNeo documentation. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
Frequently Asked Questions
Should the module path match a Git repository URL?
For shared or published code, using the repository-shaped path you expect consumers to import is the maintainable choice. A private throwaway experiment can use another path, but changing it later requires updating imports.
Can I have several commands in one Go module?
Yes. Put each executable in its own directory, commonly under cmd/, with its own package main and func main(). Build or run a specific command by directory path.
Do I need to commit go.work?
Commit it when the repository intentionally develops multiple modules together and contributors or CI should share that setup. For a temporary local arrangement, keep it local instead.
What is the difference between go run and go build?
go run builds and executes a program for the current invocation; go build compiles without running it, making it suitable for a separate build artifact or compilation check.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
