GO-RUN(1)

💖 GO-RUN(1) — like, the go run manual, bestie 💖

okay so hi!! you're looking at the manual page for go-run from the Go programming tools and commands era, and honestly? she's a baddie. let's get into it ✨

---

🌸 NAME 🌸

go-run — compile AND run a Go program, no cap 🏃♀️💨

---

🎀 SYNOPSIS 🎀

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

that's it. that's the whole vibe. write it down 📝

---

🦋 DESCRIPTION 🦋

so Run — that's what's actually happening under the hood — it compiles and runs the named main Go package. iconic behavior tbh.

Usually the package is just a list of .go source files all chillin' in a single directory, but it can also be:

• an import path
• a file system path
• a pattern that matches a single known package

like go run . or go run my/cmd — iykyk 💅

---

✨ the version-suffix situation ✨

if your package argument has a version suffix on it (think @latest or @v1.0.0), then go run builds the program in module-aware mode and straight up ignores the go.mod file in the current directory or any parent directory, if there even is one. so rude of it, love that for us 💀

this is lowkey so useful though — you can run programs without messing with the dependencies of your main module. no side effects, just vibes 🫶

🙈 no version suffix? it gets complicated 🙈

if the package argument doesn't have a version suffix, go run might run in module-aware mode or GOPATH mode — it depends on:

• the GO111MODULE environment variable
• whether a go.mod file exists

for the full tea, go read go help modules. and if module-aware mode IS enabled, then go run runs in the context of the main module. periodt.

---

🧚 how it actually runs your binary 🧚

by default, go run runs the compiled binary directly, like:

a.out arguments...

but if you pass the -exec flag, go run invokes the binary using xprog instead:

xprog a.out arguments...

and here's the plot twist: if you don't pass -exec, AND GOOS or GOARCH is different from the system default, AND a program named go_GOOS_GOARCH_exec can be found on the current search path — then go run invokes the binary using that program. for example:

go_js_wasm_exec a.out arguments...

this is what lets you execute cross-compiled programs when a simulator or some other execution method is available. slay 🌈

---

👑 debugger info: not included 👑

by default, go run compiles the binary without generating the information that debuggers use — it does this to reduce build time (efficiency queen ⏱️).

if you want debugger info in your binary, use go build instead. different tool, different job 💅

---

💜 the $PATH thing 💜

the go command puts $GOROOT/bin at the beginning of $PATH in the subprocess environment. why? so that subprocesses which execute go commands end up using the same go as their parent. consistency!! we love to see it ✨

---

💀 important exits note 💀

the exit status of Run is not the exit status of the compiled binary. do not be fooled. do not assume. just know it. 😭

---

📚 want more? 📚

• for more about build flags, see go help build
• for more about specifying packages, see go help packages

---

🌟 SEE ALSO 🌟

• go build(1)

---

🎀 AUTHOR 🎀

this manual page was created using help2man, and afterwards the output got updated (glow-up era ✨).

it is maintained by the Debian Go Compiler Team <team+go-compiler@tracker.debian.org> for the Debian project — and it may be used by others too, they're generous like that 🫶

---

okay bestie that's the whole page!! every flag, every default, every environment variable, every path — all accounted for. you're basically a Go girlie now. go forth and go run something. mwah 💋

🌈 Go 1.27 • August 2026 • GO-RUN(1) 🌈 — that's the version and date, signing off, ILY, bye!! 💖