> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Bun.spawn()

> Launch a subprocess with Bun.spawn()

Bun provides `Bun.spawn()` for launching child processes with full control over stdio, environment variables, and process lifecycle.

## Basic Usage

```ts theme={null}
const proc = Bun.spawn(["echo", "Hello World"]);

const text = await new Response(proc.stdout).text();
console.log(text); // "Hello World\n"

await proc.exited; // Wait for process to exit
```

## Synchronous Spawning

Use `Bun.spawnSync()` for blocking process execution:

```ts theme={null}
const result = Bun.spawnSync(["ls", "-la"]);

console.log(result.stdout.toString());
console.log(result.exitCode);
```

## Options

### Command and Arguments

```ts theme={null}
Bun.spawn(["node", "script.js", "--flag"], {
  // Options
});
```

### Working Directory

```ts theme={null}
Bun.spawn(["ls"], {
  cwd: "/path/to/directory",
});
```

### Environment Variables

```ts theme={null}
Bun.spawn(["env"], {
  env: {
    ...process.env,
    CUSTOM_VAR: "value",
  },
});
```

### Standard I/O

Control stdin, stdout, and stderr:

```ts theme={null}
Bun.spawn(["cat"], {
  stdin: "inherit",  // Inherit from parent
  stdout: "pipe",    // Capture output
  stderr: "ignore",  // Discard errors
});
```

Options:

* `"pipe"` - Capture the stream (default)
* `"inherit"` - Pass through from parent process
* `"ignore"` - Discard the stream
* `Bun.file(path)` - Read from or write to a file
* `TypedArray | ArrayBuffer` - Use a buffer
* `ReadableStream` - Pipe from a stream (stdin only)
* `number` - Use a file descriptor

### Piping to stdin

```ts theme={null}
const proc = Bun.spawn(["cat"], {
  stdin: "pipe",
});

proc.stdin.write("Hello ");
proc.stdin.write("World!");
proc.stdin.end();

const text = await new Response(proc.stdout).text();
console.log(text); // "Hello World!"
```

### IPC (Inter-Process Communication)

Enable message passing between parent and child:

```ts theme={null}
const proc = Bun.spawn(["bun", "child.js"], {
  ipc: (message) => {
    console.log("Received:", message);
  },
});

proc.send({ hello: "from parent" });
```

In the child process:

```ts theme={null}
// child.js
process.on("message", (msg) => {
  console.log("Child received:", msg);
  process.send({ reply: "from child" });
});
```

## Subprocess Object

The returned `Subprocess` object has these properties:

### Process Information

```ts theme={null}
const proc = Bun.spawn(["sleep", "10"]);

console.log(proc.pid); // Process ID
console.log(proc.exitCode); // null while running, number when exited
console.log(proc.signalCode); // Signal that terminated the process
```

### Streams

Access stdio streams:

```ts theme={null}
const proc = Bun.spawn(["cat"], {
  stdin: "pipe",
  stdout: "pipe",
  stderr: "pipe",
});

proc.stdin.write("input\n");
proc.stdin.end();

const stdout = await new Response(proc.stdout).text();
const stderr = await new Response(proc.stderr).text();
```

### Process Control

```ts theme={null}
const proc = Bun.spawn(["sleep", "100"]);

// Send a signal
proc.kill(); // SIGTERM (default)
proc.kill("SIGKILL"); // Force kill
proc.kill(9); // Using signal number

// Wait for exit
await proc.exited;
console.log("Process exited with code:", proc.exitCode);
```

### Resource Usage

Get CPU and memory statistics:

```ts theme={null}
const proc = Bun.spawn(["node", "heavy-script.js"]);
await proc.exited;

const usage = proc.resourceUsage();
console.log("User CPU time:", usage.userCPUTime);
console.log("System CPU time:", usage.systemCPUTime);
console.log("Max RSS:", usage.maxRSS);
```

## Timeouts and Abortion

### Using AbortSignal

```ts theme={null}
const controller = new AbortController();

const proc = Bun.spawn(["sleep", "100"], {
  signal: controller.signal,
});

// Abort after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  await proc.exited;
} catch (err) {
  console.log("Process was aborted");
}
```

### Built-in Timeout

```ts theme={null}
const proc = Bun.spawn(["sleep", "100"], {
  timeout: 5000, // Kill after 5 seconds
});
```

## Error Handling

```ts theme={null}
try {
  const proc = Bun.spawn(["nonexistent-command"]);
  await proc.exited;
  
  if (proc.exitCode !== 0) {
    const stderr = await new Response(proc.stderr).text();
    throw new Error(`Process failed: ${stderr}`);
  }
} catch (err) {
  console.error("Spawn failed:", err);
}
```

## Differences from Node.js

### Simpler API

Bun's spawn is more streamlined than Node's `child_process`:

```ts theme={null}
// Bun - streams are ReadableStream
const proc = Bun.spawn(["cat", "file.txt"]);
const text = await new Response(proc.stdout).text();

// Node - streams are Node.js Streams
const proc = spawn("cat", ["file.txt"]);
let text = "";
proc.stdout.on("data", (chunk) => text += chunk);
await new Promise(resolve => proc.on("close", resolve));
```

### Web Streams

Bun uses Web Standard `ReadableStream` and `WritableStream` instead of Node.js streams.

### Automatic Buffer Management

Bun efficiently handles large outputs without manual buffer management.

## Performance Tips

1. **Use `spawnSync` for quick commands** - Avoid async overhead for fast operations
2. **Pipe directly to files** - Use `Bun.file()` for stdin/stdout instead of buffering
3. **Stream large outputs** - Don't wait for `exited` if you only need stdout
4. **Reuse environment** - Pass `env: process.env` to avoid copying

## Platform Support

`Bun.spawn()` works on:

* macOS (x64, ARM64)
* Linux (x64, ARM64)
* Windows (x64, ARM64)

On Windows, Bun automatically handles path resolution and uses `cmd.exe` for shell scripts.