go-run

Run a Go file

$ go run [path/to/file.go]

$ go run [path/to/package]

go run [build flags] [-exec xprog] [package] [-- arguments...]

-exec xprog
    Run the program using xprog as the executable (instead of temporary binary); xprog receives arguments after --.

-a
    Force rebuild of all packages (ignore installed versions).

-asmflags flags
    Pass comma-separated assembler flags to all asm packages.

-buildflags flags
    Pass flags to external assemblers (deprecated).

-buildmode mode
    Build mode (e.g., exe, pie, plugin).

-compiler gc|gccgo
    Select compiler (default gc).

-gcflags flags
    Pass comma-separated compiler flags to gc packages.

-gccgoflags flags
    Pass flags to gccgo compiler.

-gcstackiter
    Enable GC stack iterator (off by default).

-gldebug
    Generate libdebug.so (gccgo only).

-installsuffix suffix
    Modify package path for installs.

-ldflags flags
    Pass comma-separated linker flags.

-linkshared
    Link against shared libraries.

-ldlgo path
    Dynamic linker to use (gccgo only).

-linkmode mode
    Link mode (internal, external, auto).

-mod mode
    Module download mode (auto, readonly, vendor, mod).

-modfile file
    Use alternate go.mod file.

-msan
    Enable MSan (interferes with cgo).

-murmur
    Use Murmur3 for hash-based lookups (off).

-n
    Print commands without executing.

-p procs
    Max processes during build.

-race
    Enable race detector.

-tags tags
    Comma-separated build tags.

-toolexec xprog
    Invoke toolchain binary via xprog.

-trimpath
    Omit install path from binaries.

-v
    Print verbose output.

-work
    Print temporary work directory.

package
    Go package (file, directory, module path, or .) to build and run.

arguments
    Arguments passed to the executed program (after --).

go run is a Go toolchain command that compiles one or more Go packages and immediately executes the resulting binary, primarily for development and testing. It builds the specified main package (and its dependencies) into a temporary executable in the build cache, runs it with any provided arguments, and then removes the temporary file. This avoids the need to manually build and invoke executables during rapid iteration.

It accepts all go build flags for customizing compilation, such as setting linker or compiler flags, enabling race detection, or trimming paths. Unlike go build, no output binary is left on disk. For packages with a main package, it produces a standalone program; otherwise, it errors.

Key use cases include quick prototyping (go run main.go), running modules (go run .), or executing with flags (go run -race main.go). It resolves imports from modules or GOPATH, downloads dependencies if needed, and supports cross-compilation via GOOS/GOARCH. However, repeated invocations rebuild everything unless cached, making it inefficient for production.

Rebuilds on every run (use go build for efficiency); temporary binaries only; no support for multiple main packages; cgo cross-compilation limited; race detector increases binary size significantly; not suitable for production deployment.

go run hello.go
Runs a simple program.

go run -race main.go -- arg1
Builds with race detector, passes arg1.

go run github.com/user/project
Fetches and runs remote module.

go run -ldflags="-s -w" .
Strips symbols from current package.

0 on success; non-zero on build failure, program panic, or non-zero program exit.

Introduced in 2009 with the first Go release (r16, November 2009) by Google developers Robert Griesemer, Rob Pike, and Ken Thompson to simplify development workflows. Evolved with Go modules in 1.11 (2018), MSAN/race support in later versions, and trimpath in Go 1.13.

go(1), go-build(1), go-install(1), go-mod(1)