os/exec

Running a command

You build a *exec.Cmd with exec.Command(name, args...) and then choose how to run it. The three common entry points trade convenience for control:

import "os/exec"

// 1. Run and wait — error only. You must wire Stdout yourself to see output.
cmd := exec.Command("git", "status", "--porcelain")
err := cmd.Run()

// 2. Output — run, wait, and return stdout as []byte (the usual choice).
out, err := exec.Command("git", "rev-parse", "HEAD").Output()
fmt.Printf("commit: %s", out)

// 3. CombinedOutput — stdout and stderr merged into one []byte.
out, err = exec.Command("go", "vet", "./...").CombinedOutput()

Each argument is separate — exec.Command("ls", "-l", "/tmp"), never exec.Command("ls -l /tmp"). There is no shell to split the string, so spaces in a filename “just work” and hostile input can’t smuggle in ; rm -rf /.

graph LR
C["exec.Command(name, args...)"] --> CMD["*exec.Cmd"]
CMD -->|"Run()"| W["wait → error"]
CMD -->|"Output()"| O["stdout []byte + error"]
CMD -->|"Start() + Wait()"| A["async: run while you do other work"]

Capturing output and exit codes

Output() returns stdout; when the program exits non-zero, the error is a concrete *exec.ExitError carrying the exit code (and, with Output(), the captured stderr):

out, err := exec.Command("go", "build", "./...").Output()
if err != nil {
	var ee *exec.ExitError
	if errors.As(err, &ee) {
		fmt.Printf("build failed (exit %d):\n%s", ee.ExitCode(), ee.Stderr)
	} else {
		// e.g. the program wasn't found on PATH
		fmt.Println("could not run:", err)
	}
	return
}
fmt.Printf("ok: %s", out)

A nil error means the process exited 0. Distinguish “ran and failed” (*exec.ExitError) from “couldn’t start” (a LookPath/permission error) — they need different handling.

Streaming, pipes, and stdin

For long output, don’t buffer it all — wire the child’s streams to yours (or to a file). For full control, attach pipes:

// Stream child output straight to this process's stdout/stderr.
cmd := exec.Command("make", "build")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
cmd.Run()

// Feed stdin from a string.
cmd = exec.Command("grep", "needle")
cmd.Stdin = strings.NewReader("hay\nneedle\nstack\n")
out, _ := cmd.Output() // "needle\n"

// A pipe lets you read incrementally while the command runs.
cmd = exec.Command("tail", "-f", "app.log")
stdout, _ := cmd.StdoutPipe()
cmd.Start()
scanner := bufio.NewScanner(stdout)
for scanner.Scan() {
	fmt.Println("line:", scanner.Text())
}
cmd.Wait()

Start() launches without waiting; pair it with Wait() (after you’ve drained the pipes) to reap the process. cmd.Stdout/Stdin/Stderr accept any io.Writer/io.Reader, so a bytes.Buffer, a file, or a network connection all work.

Timeouts, environment, and working directory

A child process should almost always have a deadline. exec.CommandContext kills it when the context is cancelled. You can also set its environment and working directory:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

cmd := exec.CommandContext(ctx, "slow-tool", "--big")
cmd.Dir = "/srv/data"                          // working directory
cmd.Env = append(os.Environ(), "LANG=C")        // inherit + override
if err := cmd.Run(); err != nil {
	if ctx.Err() == context.DeadlineExceeded {
		fmt.Println("timed out, process killed")
	}
}

cmd.Env = nil (the default) inherits the parent’s environment; setting it replaces the whole environment, so build on os.Environ() when you only mean to add a variable.

Reference

See also

• files & os — wire a child’s streams to files; os.Environ for its environment.
• CLI Tools with flag — parse your own flags, then shell out to other tools.
• context — CommandContext for deadlines and cancellation.
• fmt & io — cmd.Stdout/Stdin accept any io.Writer/io.Reader.

Next: prove your code works before it ships — Testing Basics.

Related topics