go run: Usage, Options & Common CI Errors

Compile and run a Go main package in one step.

go run compiles a main package to a temporary location and runs it, then discards the binary. It is convenient for scripts and tools but not how you ship a binary.

What it does

Builds the named main package into a temp directory, executes it, and cleans up. Arguments after the package path are passed to the program, not to go.

Common usage

go run .                          # run main in the current dir
go run ./cmd/server               # run a specific main package
go run main.go                    # run a single file
go run . --port 8080 --verbose    # pass program flags

Common CI error: runs a non-main package

go run ./pkg fails with "go run: cannot run non-main package" because the target is a library. go run only works on package main. Fix: point it at the directory holding func main() (e.g. ./cmd/tool), or use go build / go test for library packages.

Options

Related guides