Process Management with `std::process::Command`

18 min read

Shelling out to another program is something every real-world tool does eventually: invoking git, running a formatter, kicking off a build step, or piping data through a Unix utility. In Node you reach for child_process; in Rust the standard library ships std::process::Command, a fluent builder that spawns subprocesses, wires up their pipes, and reports their exit status — all without any external crate.

Quick Overview

std::process::Command is a builder for launching external programs. You configure the executable, its arguments, environment, working directory, and how its standard streams are connected, then either run it to completion or spawn it and manage it as a live Child. For a senior TypeScript/JavaScript developer it maps almost one-to-one onto Node’s child_process (spawn, exec, execFile) — but it is synchronous by default, strongly typed, and forces you to handle the “could not even start the program” error separately from “the program ran but exited non-zero.”

Note: The current stable toolchain is Rust 1.96.0 on the 2024 edition, which cargo new selects automatically. Every Rust snippet below was compiled and run on stable; the output shown is the real program output.

TypeScript/JavaScript Example

In Node, the child_process module gives you several entry points. spawn streams output and is the workhorse; execFile/exec buffer the whole output into a callback or promise. A realistic “run a command, capture its output, react to its exit code” flow looks like this:

1
// runner.ts — Node v22
2
import { spawn } from "node:child_process";
3
import { once } from "node:events";
4

5
interface RunResult {
6
  code: number | null; // null when the process was killed by a signal
7
  stdout: string;
8
  stderr: string;
9
}
10

11
async function run(
12
  program: string,
13
  args: string[],
14
  env: Record<string, string>,
15
): Promise<RunResult> {
16
  const child = spawn(program, args, {
17
    // Merge a few extra variables on top of the parent's environment.
18
    env: { ...process.env, ...env },
19
    stdio: ["ignore", "pipe", "pipe"],
20
  });
21

22
  let stdout = "";
23
  let stderr = "";
24
  child.stdout.on("data", (chunk) => (stdout += chunk));
25
  child.stderr.on("data", (chunk) => (stderr += chunk));
26

27
  // `spawn` emits "error" if the binary cannot be launched at all,
28
  // and "close" once it has exited.
29
  const [code] = (await once(child, "close")) as [number | null];
30
  return { code, stdout, stderr };
31
}
32

33
const result = await run("git", ["rev-parse", "--abbrev-ref", "HEAD"], {});
34
if (result.code === 0) {
35
  console.log("branch:", result.stdout.trim());
36
} else {
37
  console.error("git failed:", result.stderr.trim());
38
}

A few things a TypeScript developer takes for granted here:

spawn is asynchronous — it returns immediately and you await events.
The distinction between “could not launch the binary” (error event) and “the binary exited non-zero” (code !== 0) is real but easy to conflate, because both surface through the same ChildProcess object.
code is null when the child was terminated by a signal rather than exiting normally.

Rust Equivalent

The same idea in Rust. Command is the builder, .output() runs it to completion and buffers stdout/stderr, and the returned Output carries the exit status:

1
use std::process::Command;
2

3
fn main() {
4
    let output = Command::new("git")
5
        .args(["rev-parse", "--abbrev-ref", "HEAD"])
6
        .output() // runs to completion, capturing stdout + stderr
7
        .expect("failed to launch git"); // Err only if git could not start
8

9
    if output.status.success() {
10
        let branch = String::from_utf8_lossy(&output.stdout);
11
        println!("branch: {}", branch.trim());
12
    } else {
13
        let err = String::from_utf8_lossy(&output.stderr);
14
        eprintln!("git failed: {}", err.trim());
15
    }
16
}

The two failure modes that blur together in Node are separate and explicit in Rust:

.output() returns Result<Output, io::Error>. The Err case means the program could not be started (binary not found, no permission, etc.).
If it started, you get Ok(Output), and output.status.success() tells you whether it exited with code 0.

Here is the simplest possible run — fire a command and inspect its ExitStatus. This is the analogue of Node’s spawn with inherited stdio (the child writes directly to your terminal):

1
use std::process::Command;
2

3
fn main() {
4
    let status = Command::new("echo")
5
        .arg("Hello from a subprocess")
6
        .status() // child inherits our stdout/stderr; we just get the status
7
        .expect("failed to start echo");
8

9
    println!("echo exited with: {status}");
10
    println!("success? {}", status.success());
11
    println!("code: {:?}", status.code());
12
}

Real output:

1
Hello from a subprocess
2
echo exited with: exit status: 0
3
success? true
4
code: Some(0)

Detailed Explanation

std::process::Command follows the builder pattern (see 03-functions/04_higher-order.md for how method chaining works in Rust). Command::new("git") returns a Command; every configuration method takes &mut self and returns &mut Self, so calls chain. Nothing actually happens until you call one of the three terminal methods:

Method	What it does	Node analogue
`.status()`	Runs to completion; child inherits the parent’s stdin/stdout/stderr; returns `ExitStatus`	`spawn` with `stdio: "inherit"` then await `close`
`.output()`	Runs to completion; captures stdout + stderr into a buffer; returns `Output`	`execFile` / `exec`
`.spawn()`	Starts the child and returns a live `Child` handle immediately, without waiting	`spawn` (the raw form)

Arguments: `.arg()` vs `.args()`

1
use std::process::Command;
2

3
fn main() {
4
    // One at a time:
5
    let mut cmd = Command::new("cargo");
6
    cmd.arg("build").arg("--release");
7

8
    // Or all at once from anything iterable:
9
    let flags = ["--locked", "--offline"];
10
    cmd.args(flags);
11

12
    println!("{cmd:?}");
13
}

Each argument is passed to the OS as a separate, already-tokenized string. Crucially, Rust does not run your command through a shell, so there is no word-splitting, glob expansion, or $VAR interpolation. Command::new("echo").arg("a b c") passes the single argument a b c, not three arguments. This is the same safety property as Node’s execFile (as opposed to exec, which does spawn a shell) — and it is your first line of defense against shell-injection. The security section goes deeper on why “never build a shell string from untrusted input” matters.

Capturing output: the `Output` struct

.output() returns Output, which has three fields:

1
use std::process::Command;
2

3
fn main() {
4
    let output = Command::new("echo")
5
        .arg("captured line")
6
        .output()
7
        .expect("failed to run echo");
8

9
    let stdout = String::from_utf8_lossy(&output.stdout); // Vec<u8> -> Cow<str>
10
    let stderr = String::from_utf8_lossy(&output.stderr);
11

12
    println!("status: {}", output.status);
13
    println!("stdout: {:?}", stdout.trim());
14
    println!("stderr: {:?}", stderr.trim());
15
}

Real output:

1
status: exit status: 0
2
stdout: "captured line"
3
stderr: ""

Note that output.stdout and output.stderr are Vec<u8>, not String. A subprocess can emit arbitrary bytes, so Rust hands you the raw bytes and lets you decide how to decode them. String::from_utf8_lossy replaces invalid UTF-8 with the replacement character; use String::from_utf8 if you want to treat invalid bytes as an error instead. This contrasts with Node, where stream chunks are decoded to a JavaScript string for you (and can silently corrupt non-UTF-8 output).

Exit status: `success()`, `code()`, and signals

ExitStatus answers three related questions:

status.success() — did it exit with code 0?
status.code() — Option<i32>: Some(n) for a normal exit, None if the process was terminated by a signal (Unix).
Signal death (Unix) — when code() is None, the process was killed by a signal; you can inspect which via std::os::unix::process::ExitStatusExt::signal().

1
use std::process::Command;
2

3
fn main() {
4
    let status = Command::new("ls")
5
        .arg("/nonexistent-path-xyz")
6
        .status()
7
        .expect("failed to start ls");
8

9
    println!("success? {}", status.success());
10
    println!("code: {:?}", status.code());
11
}

Real output (stderr from ls is also printed because .status() inherits it):

1
success? false
2
code: Some(1)

That Some(1) is the direct equivalent of Node’s result.code === 1. The None case (signal death) is what Node represents as code === null plus a non-null signal.

Environment variables

Each Command starts by inheriting the parent’s environment, just like Node. You can add, override, clear, or remove specific variables:

1
use std::process::Command;
2

3
fn main() {
4
    let output = Command::new("printenv")
5
        .arg("GREETING")
6
        .env_clear()                       // start from an EMPTY environment
7
        .env("GREETING", "hello from rust") // then set exactly what we want
8
        .output()
9
        .expect("failed to run printenv");
10

11
    print!("{}", String::from_utf8_lossy(&output.stdout));
12
}

Real output:

1
hello from rust

Method	Effect
`.env("KEY", "val")`	Set/override one variable (like Node’s `{ ...process.env, KEY: "val" }`)
`.envs(iter)`	Set many from an iterator of `(key, value)` pairs
`.env_remove("KEY")`	Remove one inherited variable
`.env_clear()`	Start from a completely empty environment

Working directory

.current_dir(path) sets the child’s working directory — the analogue of Node’s { cwd } option:

1
use std::process::Command;
2

3
fn main() {
4
    let output = Command::new("pwd")
5
        .current_dir("/usr")
6
        .output()
7
        .expect("failed to run pwd");
8
    print!("cwd: {}", String::from_utf8_lossy(&output.stdout));
9
}

Real output:

1
cwd: /usr

Key Differences

Concept	Node `child_process`	Rust `std::process::Command`
Default execution model	Asynchronous (event/promise based)	Synchronous (blocks until done)
Shell involved?	`exec`/`execSync` yes; `spawn`/`execFile` no	Never — no shell unless you spawn one explicitly
Captured output type	Decoded `string` (or `Buffer`)	Raw `Vec<u8>` — you decode it
”Couldn’t start” vs “ran but failed”	Both via `ChildProcess` events; easy to conflate	Distinct: `Err(io::Error)` vs `Ok(status)` with `success() == false`
Unused result	Silently ignored	`Result` is `#[must_use]`; compiler warns if you drop it
Signal-terminated child	`code === null`, `signal` set	`status.code() == None`
Reaping zombies	Automatic	You must `.wait()` (or let `Child`’s drop happen — but drop does not wait)

Synchronous by default — and how to go async

Unlike JavaScript, where everything in child_process is non-blocking (or an explicit …Sync variant), Command::output() and Command::status() block the current thread until the child exits. That is exactly what you want in a CLI tool. If you need concurrency, you have two idiomatic choices:

Spawn the child on its own thread (see threads.md) and join later.
Use an async runtime. Tokio offers a drop-in tokio::process::Command with the same builder API but async terminals (.output().await). That belongs to the async chapters; the std API here is the foundation it is built on.

Note: Rust’s std Command is blocking; the lazy-future async model (covered in the async sections) does not apply here. tokio::process is the async counterpart when you need it.

Common Pitfalls

Pitfall 1: Expecting a shell (globbing, pipes, `$VARS`)

1
use std::process::Command;
2

3
fn main() {
4
    // Does NOT do what a TS dev coming from `exec` expects.
5
    // There is no shell, so `*.txt` is passed literally and `|` is just an argument.
6
    let output = Command::new("ls")
7
        .arg("*.txt | wc -l")
8
        .output()
9
        .expect("failed");
10
    eprintln!("{}", String::from_utf8_lossy(&output.stderr).trim());
11
}

ls receives the literal string *.txt | wc -l as one filename and complains it does not exist. If you genuinely need shell features, invoke the shell explicitly — Command::new("sh").arg("-c").arg("ls *.txt | wc -l") — but only with trusted command strings, never with interpolated user input.

Pitfall 2: Ignoring the `Result` — the compiler stops you

If you forget to handle the result of .status()/.output()/.spawn(), you get a real warning, because these return #[must_use] types:

1
use std::process::Command;
2

3
fn main() {
4
    Command::new("echo").arg("hi").status();
5
}

Real cargo build warning:

1
warning: unused `Result` that must be used
2
 --> src/bin/warn1.rs:4:5
3
  |
4
4 |     Command::new("echo").arg("hi").status();
5
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6
  |
7
  = note: this `Result` may be an `Err` variant, which should be handled
8
  = note: `#[warn(unused_must_use)]` on by default
9
help: use `let _ = ...` to ignore the resulting value
10
  |
11
4 |     let _ = Command::new("echo").arg("hi").status();
12
  |     +++++++

In Node, a fire-and-forget spawn whose error event you never listen for can crash the whole process with an uncaught exception. Rust catches the omission at compile time instead.

Pitfall 3: Moving `child.stdout` out twice

child.stdout is an Option<ChildStdout>; calling .unwrap() or .take() moves the value out, so you can only do it once:

1
use std::process::{Command, Stdio};
2

3
fn main() -> std::io::Result<()> {
4
    let child = Command::new("echo")
5
        .arg("hi")
6
        .stdout(Stdio::piped())
7
        .spawn()?;
8

9
    let out1 = child.stdout.unwrap();
10
    let out2 = child.stdout.unwrap(); // does not compile (error[E0382]: use of moved value)
11
    drop((out1, out2));
12
    Ok(())
13
}

Real cargo build error:

1
error[E0382]: use of moved value: `child.stdout`
2
    --> src/bin/err1.rs:10:16
3
     |
4
   9 |     let out1 = child.stdout.unwrap();
5
     |                ------------ -------- `child.stdout` moved due to this method call
6
     |                |
7
     |                help: consider calling `.as_ref()` or `.as_mut()` to borrow the type's contents
8
  10 |     let out2 = child.stdout.unwrap(); // does not compile (error[E0382]: use of moved value)
9
     |                ^^^^^^^^^^^^ value used here after move
10
     |
11
note: `Option::<T>::unwrap` takes ownership of the receiver `self`, which moves `child.stdout`

The idiomatic fix is let stdout = child.stdout.take().expect("stdout was piped");, which leaves None behind and hands you the stream once. See 05-ownership/06_move-copy-clone.md for why ownership transfers like this are the norm.

Pitfall 4: Deadlocking on full pipes

If you .spawn() a child with both stdin and stdout piped, write a large amount to its stdin, and only then read its stdout, you can deadlock: the child’s stdout pipe buffer fills, the child blocks trying to write, and so it never drains your stdin. Two safe patterns:

For modest data, use .output() / child.wait_with_output(), which handle the draining for you.
For large or streaming data, read stdout on a separate thread (or with an async runtime) while you write stdin.

Also remember to close the child’s stdin (by dropping the ChildStdin) when you are done writing — otherwise a tool like wc waits forever for EOF. The stdin example below shows the idiomatic scoped drop.

Pitfall 5: Expecting drop to wait

Dropping a Child does not wait for it and does not kill it — the subprocess keeps running, orphaned, and may become a zombie until reaped. Always call .wait() (or .wait_with_output()), or explicitly .kill() then .wait(), before the handle goes out of scope.

Best Practices

Prefer .output() or .status() over .spawn() unless you specifically need to interact with the live process. They are simpler and harder to misuse.
Treat the two failure modes separately. Pattern-match the Result for “could not start,” then check status.success() for “started but failed.” Conflating them is the most common bug ported from JavaScript.
Never assemble a shell string from untrusted input. Pass arguments individually via .arg()/.args(); the OS receives them pre-tokenized, so injection is impossible. Reserve sh -c "…" for fully trusted, static commands. (More in ../27-security/README.md.)
Decode output explicitly. Use String::from_utf8_lossy when you expect text and tolerate garbage, or String::from_utf8 when invalid UTF-8 should be an error.
Always reap children. Call .wait() after .spawn(); do not rely on drop.
Stream long-running output with a BufReader over child.stdout instead of buffering everything, so users see progress.
Propagate exit codes from wrapper tools with std::process::exit(code) so callers and CI see the real status.

Real-World Example

A miniature task runner — the kind of glue script you might otherwise write in npm/bash. It runs a sequence of named shell tasks with a shared environment, streams each task’s output live with a prefix, tracks failures, and exits non-zero if anything failed (so CI notices):

1
use std::collections::HashMap;
2
use std::io::{BufRead, BufReader};
3
use std::process::{Command, Stdio};
4

5
/// What we learned after running one task.
6
struct TaskOutcome {
7
    name: String,
8
    code: Option<i32>,
9
}
10

11
/// Run a shell command, streaming its stdout live with a per-task prefix,
12
/// then report the exit code.
13
fn run_task(
14
    name: &str,
15
    shell_cmd: &str,
16
    env: &HashMap<&str, &str>,
17
) -> std::io::Result<TaskOutcome> {
18
    let mut child = Command::new("sh")
19
        .arg("-c")
20
        .arg(shell_cmd)
21
        .envs(env) // merged on top of the inherited environment
22
        .stdout(Stdio::piped())
23
        .stderr(Stdio::piped())
24
        .spawn()?;
25

26
    // Take the stream once, then read it line by line as the child produces it.
27
    let stdout = child.stdout.take().expect("stdout was piped");
28
    for line in BufReader::new(stdout).lines() {
29
        println!("[{name}] {}", line?);
30
    }
31

32
    let status = child.wait()?; // reap the child and get its status
33
    Ok(TaskOutcome { name: name.to_string(), code: status.code() })
34
}
35

36
fn main() -> std::io::Result<()> {
37
    let mut env = HashMap::new();
38
    env.insert("NODE_ENV", "production");
39

40
    let tasks = [
41
        ("env", "echo building in $NODE_ENV mode"),
42
        ("count", "seq 1 3"),
43
        ("lint", "echo 'lint: 1 problem' && exit 1"),
44
    ];
45

46
    let mut failed = 0;
47
    for (name, cmd) in tasks {
48
        let outcome = run_task(name, cmd, &env)?;
49
        match outcome.code {
50
            Some(0) => println!("OK   {}", outcome.name),
51
            other => {
52
                failed += 1;
53
                println!("FAIL {} (code {:?})", outcome.name, other);
54
            }
55
        }
56
    }
57

58
    println!("{failed} task(s) failed");
59
    if failed > 0 {
60
        std::process::exit(1); // propagate failure to the caller / CI
61
    }
62
    Ok(())
63
}

Real output (and the process exits with code 1):

1
[env] building in production mode
2
OK   env
3
[count] 1
4
[count] 2
5
[count] 3
6
OK   count
7
[lint] lint: 1 problem
8
FAIL lint (code Some(1))
9
1 task(s) failed

This is the synchronous, type-checked cousin of a Node task runner. Notice there is no callback nesting and no event wiring: the control flow reads top-to-bottom, and every fallible step is a ? that short-circuits on error.

Exercises

Exercise 1: Capture and trim

Difficulty: Beginner

Objective: Get comfortable with .output() and decoding stdout.

Instructions: Write a program that runs date "+%Y" (the date command with that format string as a single argument), captures the output, trims trailing whitespace, and prints Current year: <year>. Handle the “could not start” case with expect, and verify status.success() before trusting the output.

Solution

1
use std::process::Command;
2

3
fn main() {
4
    let output = Command::new("date")
5
        .arg("+%Y")
6
        .output()
7
        .expect("failed to run date");
8

9
    if output.status.success() {
10
        let year = String::from_utf8_lossy(&output.stdout);
11
        println!("Current year: {}", year.trim());
12
    } else {
13
        eprintln!("date failed: {}", String::from_utf8_lossy(&output.stderr).trim());
14
    }
15
}

A real run prints something like Current year: 2026. String::from_utf8_lossy turns the captured Vec<u8> into text, and .trim() removes the trailing newline date emits.

Exercise 2: Pipe data into a child’s stdin

Difficulty: Intermediate

Objective: Spawn a child with a piped stdin, write to it, and read the result back — without deadlocking.

Instructions: Spawn wc -w with Stdio::piped() for both stdin and stdout. Write the bytes "one two three four five\n" to the child’s stdin, then drop the stdin handle so the child sees EOF. Collect the child’s output with wait_with_output() and print the word count. (Expected: 5.)

Solution

1
use std::io::Write;
2
use std::process::{Command, Stdio};
3

4
fn main() -> std::io::Result<()> {
5
    let mut child = Command::new("wc")
6
        .arg("-w")
7
        .stdin(Stdio::piped())
8
        .stdout(Stdio::piped())
9
        .spawn()?;
10

11
    // Inner scope: when `stdin` is dropped here, the pipe closes and the
12
    // child sees EOF — otherwise `wc` would wait forever for more input.
13
    {
14
        let mut stdin = child.stdin.take().expect("child has no stdin");
15
        stdin.write_all(b"one two three four five\n")?;
16
    }
17

18
    let output = child.wait_with_output()?;
19
    print!("word count: {}", String::from_utf8_lossy(&output.stdout));
20
    Ok(())
21
}

Real output:

1
word count:        5

Note: The exact leading-space padding of wc output is platform-dependent (macOS and GNU coreutils pad differently); the count 5 is the part that matters.

The scoped block is the key detail: dropping ChildStdin closes the write end of the pipe, and only then does wc finish reading and produce its count. Forgetting to close stdin is the classic cause of a hung subprocess.

Exercise 3: Spawn, time out, and kill

Difficulty: Advanced

Objective: Manage a long-running Child directly: start it, give it a moment, then terminate it and reap it.

Instructions: Spawn sleep 30. Print its PID via child.id(). Sleep the main thread for 100 ms, then call child.kill() followed by child.wait(). Print whether the final status was successful and what status.code() returns. Explain in a comment why the code is None.

Solution

1
use std::process::Command;
2
use std::time::Duration;
3

4
fn main() -> std::io::Result<()> {
5
    let mut child = Command::new("sleep").arg("30").spawn()?;
6
    println!("spawned sleep with pid {}", child.id());
7

8
    std::thread::sleep(Duration::from_millis(100));
9

10
    child.kill()?;              // send SIGKILL to the child
11
    let status = child.wait()?; // reap it so it is not left as a zombie
12

13
    println!("after kill, success? {}", status.success());
14
    // code() is None because the process was terminated by a signal
15
    // (SIGKILL) rather than exiting normally with a numeric code.
16
    println!("code: {:?}", status.code());
17
    Ok(())
18
}

Real output (the PID varies):

1
spawned sleep with pid 64828
2
after kill, success? false
3
code: None

kill() sends SIGKILL; because the process died from a signal rather than calling exit, status.code() is None — the Rust equivalent of Node’s code === null with a non-null signal. The follow-up wait() reaps the child so it does not linger as a zombie.

Process Management with std::process::Command

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Arguments: .arg() vs .args()

Capturing output: the Output struct

Exit status: success(), code(), and signals

Environment variables

Working directory

Key Differences

Synchronous by default — and how to go async

Common Pitfalls

Pitfall 1: Expecting a shell (globbing, pipes, $VARS)

Pitfall 2: Ignoring the Result — the compiler stops you

Pitfall 3: Moving child.stdout out twice

Pitfall 4: Deadlocking on full pipes

Pitfall 5: Expecting drop to wait

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Capture and trim

Exercise 2: Pipe data into a child’s stdin

Exercise 3: Spawn, time out, and kill

Process Management with `std::process::Command`

Arguments: `.arg()` vs `.args()`

Capturing output: the `Output` struct

Exit status: `success()`, `code()`, and signals

Pitfall 1: Expecting a shell (globbing, pipes, `$VARS`)

Pitfall 2: Ignoring the `Result` — the compiler stops you

Pitfall 3: Moving `child.stdout` out twice