Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท The go Command and Tools

The go run command

Reference for the go run command: run a package or single file, pass arguments, exit codes, build flags, running remote versions and what it leaves behind.

go run compiles a Go main package and immediately runs the resulting program. It is the quickest way to try code: no output file to name, nothing to clean up. The executable is built in a temporary directory and deleted afterwards, and the exit status of your program is reported as the status of go run itself.

You can run a whole package (go run .), a list of files (go run main.go util.go), or a package by import path, optionally with a version (go run example.com/tool@latest). Everything after the package argument is passed to your program, not to the go tool.

Terminal
go run .                       # the package in the current directory
go run main.go                 # one file
go run ./cmd/server -port 9000 # a package, then the program's own arguments
go run golang.org/x/tools/cmd/stringer@v0.30.0 -help

Try it

The site compiles and runs these programs for you; they show what a program started by go run sees, and how its result comes back.

Go What the program sees: arguments and build info

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Exit status travels back to the caller

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Terminal
go run [build flags] [-exec xprog] package [arguments...]
Part Description
package A directory (., ./cmd/app), a list of .go files, or an import path. Must be (or contain) a main package.
arguments... Everything after the package is passed unchanged to the program, including words that start with -.
package@version Run a command at a specific module version (@latest, @v1.2.3) without touching your go.mod. Added in Go 1.17.
-exec xprog Run the binary through another program, for example an emulator or sudo.
Build flags The same flags as go build: -race, -tags, -ldflags, -gcflags, -trimpath, -v, -x, -n.

Exit behavior: if the program exits with a nonzero status, go run prints exit status N to standard error and itself reports failure. Scripts that need the exact exit code should build the binary and run it directly. Compile errors stop before anything runs, and no program output appears.

Usage notes

  • go run . versus go run main.go. A file list ignores other files in the package, so helper files must be listed too. Prefer go run . once a program has more than one file.
  • Standard input works. The program inherits stdin, stdout and stderr, so interactive programs behave normally. Ctrl+C reaches your program.
  • Not for production. A binary built by go run lives in a temporary directory, so os.Executable() and relative paths based on it are not meaningful. Use go build for anything you deploy.
  • Caching makes repeats fast. The build cache means an unchanged program only needs to be linked again. The first run after an edit pays for compilation.
  • Test files are rejected. go run foo_test.go fails; use go test.
  • Remote versions. go run pkg@version ignores the current module's go.mod replace and exclude directives, so it behaves like go install followed by a run. It builds with module-aware mode even outside a module.
  • Watching for changes is not built in. Tools such as air or watchexec rerun go run on every save.
  • Cross-compiling. With a GOOS or GOARCH different from your machine, go run builds a binary your system cannot execute, so it fails unless you provide -exec with a suitable emulator.