Bun.Spawn object | API Reference | Bun

Path to the executable to run in the subprocess. This defaults to cmds[0].

One use-case for this is for applications which wrap other applications or to simulate a symlink.

The current working directory of the process

Defaults to process.cwd()

Run the child in a separate process group, detached from the parent.

Note: stdio may keep the parent process alive. Pass stdio: ["ignore", "ignore", "ignore"] to the spawn constructor to prevent this.

The environment variables of the process

Defaults to process.env as it was when the current Bun process launched.

Changes to process.env at runtime won't automatically be reflected in the default value. For that, you can pass process.env explicitly.

The signal to use when killing the process after a timeout, when the AbortSignal is aborted, or when the process goes over the maxBuffer limit.

// Kill the process with SIGKILL after 5 seconds
const subprocess = Bun.spawn({
cmd: ["sleep", "10"],
timeout: 5000,
killSignal: "SIGKILL",
});

The maximum number of bytes the process may output. If the process goes over this limit, it is killed with signal killSignal (defaults to SIGTERM).

The serialization format to use for IPC messages. Defaults to "advanced".

To communicate with Node.js processes, use "json".

When ipc is not specified, this is ignored.

An AbortSignal that can be used to abort the subprocess.

This is useful for aborting a subprocess when some other part of the program is aborted, such as a fetch response.

If the signal is aborted, the process will be killed with the signal specified by killSignal (defaults to SIGTERM).

const controller = new AbortController();
const { signal } = controller;
const start = performance.now();
const subprocess = Bun.spawn({
cmd: ["sleep", "100"],
signal,
});
await Bun.sleep(1);
controller.abort();
await subprocess.exited;
const end = performance.now();
console.log(end - start); // 1ms instead of 101ms

The file descriptor for the standard error. It may be:

The file descriptor for the standard input. It may be:

The standard file descriptors of the process, in the form [stdin, stdout, stderr]. This overrides the stdin, stdout, and stderr properties.

For stdin you may pass:

For stdout and stdin you may pass:

The file descriptor for the standard output. It may be:

The maximum amount of time the process is allowed to run in milliseconds.

If the timeout is reached, the process will be killed with the signal specified by killSignal (defaults to SIGTERM).

// Kill the process after 5 seconds
const subprocess = Bun.spawn({
cmd: ["sleep", "10"],
timeout: 5000,
});
await subprocess.exited; // Will resolve after 5 seconds

If true, the subprocess will have a hidden window.

If true, no quoting or escaping of arguments is done on Windows.

When specified, Bun will open an IPC channel to the subprocess. The passed callback is called for incoming messages, and subprocess.send can send messages to the subprocess. Messages are serialized using the JSC serialize API, which allows for the same types that postMessage/structuredClone supports.

The subprocess can send and receive messages by using process.send and process.on("message"), respectively. This is the same API as what Node.js exposes when child_process.fork() is used.

Currently, this is only compatible with processes that are other bun instances.

The Subprocess that received the message

Called exactly once when the IPC channel between the parent and this subprocess is closed. After this runs, no further IPC messages will be delivered.

When it fires:

Notes:

const subprocess = spawn({
cmd: ["echo", "hello"],
ipc: (message) => console.log(message),
onDisconnect: () => {
console.log("IPC channel disconnected");
},
});

Callback that runs when the Subprocess exits

This is called even if the process exits with a non-zero exit code.

Warning: this may run before the Bun.spawn function returns.

A simple alternative is await subprocess.exited.

If an error occurred in the call to waitpid2, this will be the error.

const subprocess = spawn({
cmd: ["echo", "hello"],
onExit: (subprocess, code) => {
console.log(`Process exited with code ${code}`);
},
});

Path to the executable to run in the subprocess. This defaults to cmds[0].

One use-case for this is for applications which wrap other applications or to simulate a symlink.

The current working directory of the process

Defaults to process.cwd()

Run the child in a separate process group, detached from the parent.

Note: stdio may keep the parent process alive. Pass stdio: ["ignore", "ignore", "ignore"] to the spawn constructor to prevent this.

The environment variables of the process

Defaults to process.env as it was when the current Bun process launched.

Changes to process.env at runtime won't automatically be reflected in the default value. For that, you can pass process.env explicitly.

The signal to use when killing the process after a timeout, when the AbortSignal is aborted, or when the process goes over the maxBuffer limit.

// Kill the process with SIGKILL after 5 seconds
const subprocess = Bun.spawn({
cmd: ["sleep", "10"],
timeout: 5000,
killSignal: "SIGKILL",
});

If true, stdout and stderr pipes will not automatically start reading data. Reading will only begin when you access the stdout or stderr properties.

This can improve performance when you don't need to read output immediately.

const subprocess = Bun.spawn({
cmd: ["echo", "hello"],
lazy: true, // Don't start reading stdout until accessed
});
// stdout reading hasn't started yet
await subprocess.stdout.text(); // Now reading starts

The maximum number of bytes the process may output. If the process goes over this limit, it is killed with signal killSignal (defaults to SIGTERM).

The serialization format to use for IPC messages. Defaults to "advanced".

To communicate with Node.js processes, use "json".

When ipc is not specified, this is ignored.

An AbortSignal that can be used to abort the subprocess.

This is useful for aborting a subprocess when some other part of the program is aborted, such as a fetch response.

If the signal is aborted, the process will be killed with the signal specified by killSignal (defaults to SIGTERM).

const controller = new AbortController();
const { signal } = controller;
const start = performance.now();
const subprocess = Bun.spawn({
cmd: ["sleep", "100"],
signal,
});
await Bun.sleep(1);
controller.abort();
await subprocess.exited;
const end = performance.now();
console.log(end - start); // 1ms instead of 101ms

The file descriptor for the standard error. It may be:

The file descriptor for the standard input. It may be:

The standard file descriptors of the process, in the form [stdin, stdout, stderr]. This overrides the stdin, stdout, and stderr properties.

For stdin you may pass:

For stdout and stdin you may pass:

The file descriptor for the standard output. It may be:

Spawn the subprocess with a pseudo-terminal (PTY) attached.

When this option is provided:

Only available on POSIX systems (Linux, macOS).

const proc = Bun.spawn(["bash"], {
terminal: {
cols: 80,
rows: 24,
data: (term, data) => console.log(data.toString()),
},
});

proc.terminal.write("echo hello\n");
await proc.exited;
proc.terminal.close();

You can also pass an existing Terminal object for reuse across multiple spawns:

const terminal = new Bun.Terminal({ ... });
const proc1 = Bun.spawn(["echo", "first"], { terminal });
await proc1.exited;
const proc2 = Bun.spawn(["echo", "second"], { terminal });
await proc2.exited;
terminal.close();

The maximum amount of time the process is allowed to run in milliseconds.

If the timeout is reached, the process will be killed with the signal specified by killSignal (defaults to SIGTERM).

// Kill the process after 5 seconds
const subprocess = Bun.spawn({
cmd: ["sleep", "10"],
timeout: 5000,
});
await subprocess.exited; // Will resolve after 5 seconds

If true, the subprocess will have a hidden window.

If true, no quoting or escaping of arguments is done on Windows.

When specified, Bun will open an IPC channel to the subprocess. The passed callback is called for incoming messages, and subprocess.send can send messages to the subprocess. Messages are serialized using the JSC serialize API, which allows for the same types that postMessage/structuredClone supports.

The subprocess can send and receive messages by using process.send and process.on("message"), respectively. This is the same API as what Node.js exposes when child_process.fork() is used.

Currently, this is only compatible with processes that are other bun instances.

The Subprocess that received the message

Called exactly once when the IPC channel between the parent and this subprocess is closed. After this runs, no further IPC messages will be delivered.

When it fires:

Notes:

const subprocess = spawn({
cmd: ["echo", "hello"],
ipc: (message) => console.log(message),
onDisconnect: () => {
console.log("IPC channel disconnected");
},
});

Callback that runs when the Subprocess exits

This is called even if the process exits with a non-zero exit code.

Warning: this may run before the Bun.spawn function returns.

A simple alternative is await subprocess.exited.

If an error occurred in the call to waitpid2, this will be the error.

const subprocess = spawn({
cmd: ["echo", "hello"],
onExit: (subprocess, code) => {
console.log(`Process exited with code ${code}`);
},
});

Path to the executable to run in the subprocess. This defaults to cmds[0].

One use-case for this is for applications which wrap other applications or to simulate a symlink.

The current working directory of the process

Defaults to process.cwd()

Run the child in a separate process group, detached from the parent.

Note: stdio may keep the parent process alive. Pass stdio: ["ignore", "ignore", "ignore"] to the spawn constructor to prevent this.

The environment variables of the process

Defaults to process.env as it was when the current Bun process launched.

Changes to process.env at runtime won't automatically be reflected in the default value. For that, you can pass process.env explicitly.

The signal to use when killing the process after a timeout, when the AbortSignal is aborted, or when the process goes over the maxBuffer limit.

// Kill the process with SIGKILL after 5 seconds
const subprocess = Bun.spawn({
cmd: ["sleep", "10"],
timeout: 5000,
killSignal: "SIGKILL",
});

The maximum number of bytes the process may output. If the process goes over this limit, it is killed with signal killSignal (defaults to SIGTERM).

The serialization format to use for IPC messages. Defaults to "advanced".

To communicate with Node.js processes, use "json".

When ipc is not specified, this is ignored.

An AbortSignal that can be used to abort the subprocess.

This is useful for aborting a subprocess when some other part of the program is aborted, such as a fetch response.

If the signal is aborted, the process will be killed with the signal specified by killSignal (defaults to SIGTERM).

const controller = new AbortController();
const { signal } = controller;
const start = performance.now();
const subprocess = Bun.spawn({
cmd: ["sleep", "100"],
signal,
});
await Bun.sleep(1);
controller.abort();
await subprocess.exited;
const end = performance.now();
console.log(end - start); // 1ms instead of 101ms

The file descriptor for the standard error. It may be:

The file descriptor for the standard input. It may be:

The standard file descriptors of the process, in the form [stdin, stdout, stderr]. This overrides the stdin, stdout, and stderr properties.

For stdin you may pass:

For stdout and stdin you may pass:

The file descriptor for the standard output. It may be:

The maximum amount of time the process is allowed to run in milliseconds.

If the timeout is reached, the process will be killed with the signal specified by killSignal (defaults to SIGTERM).

// Kill the process after 5 seconds
const subprocess = Bun.spawn({
cmd: ["sleep", "10"],
timeout: 5000,
});
await subprocess.exited; // Will resolve after 5 seconds

If true, the subprocess will have a hidden window.

If true, no quoting or escaping of arguments is done on Windows.

When specified, Bun will open an IPC channel to the subprocess. The passed callback is called for incoming messages, and subprocess.send can send messages to the subprocess. Messages are serialized using the JSC serialize API, which allows for the same types that postMessage/structuredClone supports.

The subprocess can send and receive messages by using process.send and process.on("message"), respectively. This is the same API as what Node.js exposes when child_process.fork() is used.

Currently, this is only compatible with processes that are other bun instances.

The Subprocess that received the message

Called exactly once when the IPC channel between the parent and this subprocess is closed. After this runs, no further IPC messages will be delivered.

When it fires:

Notes:

const subprocess = spawn({
cmd: ["echo", "hello"],
ipc: (message) => console.log(message),
onDisconnect: () => {
console.log("IPC channel disconnected");
},
});

Callback that runs when the Subprocess exits

This is called even if the process exits with a non-zero exit code.

Warning: this may run before the Bun.spawn function returns.

A simple alternative is await subprocess.exited.

If an error occurred in the call to waitpid2, this will be the error.

const subprocess = spawn({
cmd: ["echo", "hello"],
onExit: (subprocess, code) => {
console.log(`Process exited with code ${code}`);
},
});

Option for stdout/stderr

Option for stdin