BunのBun.spawnで、子プロセスを動かす方法
Bun.spawn を使うと、Bun.spawn(["git", "status"]) のように、コマンドと引数を配列で渡して子プロセスを起動できます。シェルを通さないので、空白や ; を含む値もそのまま1つの引数として渡り、出力はストリームや文字列で、終了コードは Promise で受け取れます。
git やビルドツールなどの外部コマンドを、スクリプトや CLI ツール、サーバーの中から呼びたいときに使います。
検証環境は Ubuntu 24.04(x86_64、4 CPU)、Bun 1.4.4、比べる相手は Node.js 22.23.4 です。Windows と macOS、terminal オプション(PTY)と cgroup オプションは試していません。公式ドキュメントは、検証に使った版(タグ bun-v1.4.4)の元ファイルを GitHub で確認し、リンクもそこに張っています。
配列で起動し、出力と終了コードを受け取る
Bun.spawn は Bun に組み込まれているので、import は要りません。1つ目の引数に、コマンドと引数を並べた配列を渡します(公式ドキュメントの、起動のしかたを説明した節)。
const proc = Bun.spawn(["echo", "hello", "猫 の 手; echo injected"]);
console.log("pid は数値:", typeof proc.pid === "number");
const out = await proc.stdout.text();
const code = await proc.exited;
console.log("stdout:", JSON.stringify(out));
console.log("exited:", code, "exitCode:", proc.exitCode, "signalCode:", proc.signalCode);
console.log("stderr プロパティ(既定):", proc.stderr);
bun basics.ts で実行した結果です(このあとのコードも、同じファイルの続きです)。
pid は数値: true
stdout: "hello 猫 の 手; echo injected\n"
exited: 0 exitCode: 0 signalCode: null
stderr プロパティ(既定): undefined
Bun.spawn は子プロセスの終わりを待たずに、Subprocess のオブジェクトをすぐに返します。出力は proc.stdout.text() で文字列に、終了コードは await proc.exited で受け取ります。3つ目の引数の ; echo injected は、次のコマンドとして実行されず、文字のまま echo に渡りました。日本語もそのまま届いています。
既定では、stdout は読み取れるストリームになり、stderr は親のプロセスの出力にそのまま流れるため、proc.stderr は undefined です(公式ドキュメントの、出力の受け取り方を説明した節)。エラー出力も受け取りたいときは、stderr: "pipe" を指定します。
失敗しても例外にならない。存在しないコマンドだけは例外になる
終了コードが 0 以外でも、Bun.spawn は例外を投げません。exited の値を見て分けます。
const ls = Bun.spawn(["ls", "nothing-here"], { stderr: "pipe" });
const [lsOut, lsErr, lsCode] = await Promise.all([ls.stdout.text(), ls.stderr.text(), ls.exited]);
console.log("ls の stdout:", JSON.stringify(lsOut));
console.log("ls の stderr:", JSON.stringify(lsErr));
console.log("ls の終了コード:", lsCode);
try {
Bun.spawn(["no-such-command"]);
} catch (err: any) {
console.log("例外:", err.constructor.name, err.code, err.message);
}
ls の stdout: ""
ls の stderr: "ls: cannot access 'nothing-here': No such file or directory\n"
ls の終了コード: 2
例外: Error ENOENT Executable not found in $PATH: "no-such-command"
ls は終了コード 2 で終わり、エラー出力は stderr から受け取れました。一方、PATH の中に見つからないコマンドを指定すると、Bun.spawn を呼んだ時点で ENOENT の例外になりました。await する前に投げられるので、try で囲む範囲に Bun.spawn の呼び出しそのものを入れておきます。
同じ Bun の機能でも、Bun Shell の $ は終了コードが 0 以外だと例外を投げます(Bun Shell の公式ドキュメントの、エラーの扱いを説明した節)。Bun.spawn は投げないので、失敗を見落とさないよう、exited の値を必ず確かめます。
パイプや * は使えない。必要なら sh -c を起動する
Bun.spawn はシェルを通さずにコマンドを起動するので、| や * も、ただの文字として渡ります。
const noShell = Bun.spawn(["echo", "*.ts", "|", "wc", "-l"]);
console.log("シェルなし:", JSON.stringify(await noShell.stdout.text()));
const withShell = Bun.spawn(["sh", "-c", "ls *.ts | wc -l"]);
console.log("sh -c:", JSON.stringify(await withShell.stdout.text()));
シェルなし: "*.ts | wc -l\n"
sh -c: "8\n"
sh -c で起動したほうは、作業フォルダにある .ts ファイルの数(8)を返しました。ただし、sh -c に渡す文字列に外から受け取った値を混ぜると、最初の節で見たように記号が文字のまま1つの引数として渡る、という安全さはなくなります。パイプが必要なだけなら、埋め込んだ値を1つの文字列として扱う Bun Shell の $ を使うほうが安全です(コマンドインジェクションを防ぐ仕組みを説明した、Bun Shell の公式ドキュメント)。
作業フォルダ、環境変数、標準入力を指定する
2つ目の引数のオブジェクトで、作業フォルダ(cwd)や環境変数(env)、標準入力(stdin)を指定できます。
const a = Bun.spawn(["pwd"], { cwd: "/tmp" });
console.log("cwd:", (await a.stdout.text()).trim(), "/ 親の process.cwd() は変わらない:", process.cwd() === import.meta.dir);
const b = Bun.spawn(["sh", "-c", 'echo "FOO=$FOO HOME=${HOME:-(空)}"'], { env: { FOO: "bar" } });
console.log("env: { FOO }:", (await b.stdout.text()).trim());
const c = Bun.spawn(["sh", "-c", 'echo "FOO=$FOO HOME=${HOME:+(あり)}"'], { env: { ...process.env, FOO: "bar" } });
console.log("env: { ...process.env, FOO }:", (await c.stdout.text()).trim());
cwd: /tmp / 親の process.cwd() は変わらない: true
env: { FOO }: FOO=bar HOME=(空)
env: { ...process.env, FOO }: FOO=bar HOME=(あり)
env に渡したオブジェクトは、子プロセスの環境変数のすべてになります。{ FOO: "bar" } だけを渡すと、HOME は空になりました。PATH や HOME を残したいときは、公式ドキュメントの例と同じく ...process.env を一緒に渡します。
標準入力は、既定では何も渡されません。stdin: "pipe" にすると proc.stdin に書き込めるようになり、Response や Bun.file() なども、そのまま入力にできます(公式ドキュメントの、標準入力を説明した節)。出力の先に Bun.file() を指定すれば、ファイルに書き出せます(出力先として指定できる値の一覧)。
const cat = Bun.spawn(["wc", "-c"], { stdin: "pipe" });
cat.stdin.write("hello");
cat.stdin.write(new TextEncoder().encode(" 猫"));
cat.stdin.end();
console.log("wc -c(hello と 猫 を書いた):", (await cat.stdout.text()).trim());
const sorted = Bun.spawn(["sort"], { stdin: new Response("banana\napple\ncherry\n"), stdout: Bun.file("sorted.txt") });
await sorted.exited;
console.log("sorted.txt:", JSON.stringify(await Bun.file("sorted.txt").text()), "proc.stdout:", sorted.stdout);
wc -c(hello と 猫 を書いた): 9
sorted.txt: "apple\nbanana\ncherry\n" proc.stdout: undefined
"hello"(5バイト)、空白(1バイト)、猫(UTF-8 で3バイト)の合わせて9バイトが、wc に届きました。書き終えたら end() で入力を閉じます。end() を呼ばずに、flush() だけで2秒の timeout を付けて試したところ、wc は終わらず、2秒後に SIGTERM で止められました(出力は空、exited は 143)。stdout をファイルにしたときは、proc.stdout は undefined になりました。
長く動くコマンドの出力を、届いた順に読む
proc.stdout は ReadableStream なので、for await で、届いたぶんから順に読めます。0.3秒おきに1行ずつ出すコマンドで確かめました。
const lines = Bun.spawn(["sh", "-c", "for i in 1 2 3; do echo line $i; sleep 0.3; done"]);
const t0 = performance.now();
const decoder = new TextDecoder();
for await (const chunk of lines.stdout) {
console.log(`${(performance.now() - t0).toFixed(0).padStart(4)}ms 受信:`, JSON.stringify(decoder.decode(chunk)));
}
await lines.exited;
1ms 受信: "line 1\n"
302ms 受信: "line 2\n"
604ms 受信: "line 3\n"
コマンドが終わるのを待たずに、出した行が約0.3秒おきに届きました。この検証では1回に1行ずつ届きましたが、1回に届く量は決まっていないので、行ごとに処理するときは、自分で改行で分けます。
なお、stdout を読まずに exited だけを待っても、子プロセスは詰まらずに最後まで動き、終わりました。1 MB と 100 MB を stdout に出すコマンド、stderr: "pipe" にして 1 MB をエラー出力に出すコマンドで試したところ、どれも終了コード 0 で終わっています(100 MB で155ミリ秒)。
タイムアウト、kill、AbortSignal で止める
timeout にミリ秒を指定すると、その時間で子プロセスが止められます。止めるときに送るシグナルは、既定では SIGTERM で、killSignal で変えられます。proc.kill() や AbortSignal でも止められます(公式ドキュメントの、AbortSignal とタイムアウトを説明した節)。
const t = () => performance.now();
let s = t();
const p1 = Bun.spawn(["sleep", "10"], { timeout: 500 });
console.log("timeout:", await p1.exited, p1.exitCode, p1.signalCode, "killed:", p1.killed, `${(t() - s).toFixed(0)}ms`);
s = t();
const p2 = Bun.spawn(["sleep", "10"], { timeout: 500, killSignal: "SIGKILL" });
console.log("timeout + SIGKILL:", await p2.exited, p2.exitCode, p2.signalCode, `${(t() - s).toFixed(0)}ms`);
s = t();
const p3 = Bun.spawn(["sleep", "10"]);
setTimeout(() => p3.kill(), 300);
console.log("kill():", await p3.exited, p3.exitCode, p3.signalCode, `${(t() - s).toFixed(0)}ms`);
s = t();
const ac = new AbortController();
const p4 = Bun.spawn(["sleep", "10"], { signal: ac.signal });
setTimeout(() => ac.abort(), 200);
console.log("AbortSignal:", await p4.exited, p4.exitCode, p4.signalCode, `${(t() - s).toFixed(0)}ms`);
timeout: 143 null SIGTERM killed: true 502ms
timeout + SIGKILL: 137 null SIGKILL 502ms
kill(): 143 null SIGTERM 301ms
AbortSignal: 143 null SIGTERM 201ms
どれも指定した時間で止まりました。4つとも、exited は 143(SIGTERM)や 137(SIGKILL)を返し、exitCode は null、signalCode にシグナルの名前が入りました。exited の値が 0 以外なので、終了コードで失敗を見分けるコードでも、止めた場合は失敗として扱えます。どのシグナルで止まったかを知りたいときは signalCode を見ます。
終わったときに関数を呼ばせたいときは onExit を、子プロセスが使った CPU 時間やメモリを知りたいときは、終わったあとに resourceUsage() を呼びます(公式ドキュメントの、終了の扱いを説明した節)。
await new Promise<void>((resolve) => {
Bun.spawn(["sh", "-c", "exit 3"], {
onExit(proc, exitCode, signalCode, error) {
console.log("onExit:", exitCode, signalCode, error);
resolve();
},
});
});
const p5 = Bun.spawn(["sh", "-c", "i=0; while [ $i -lt 200000 ]; do i=$((i+1)); done"]);
await p5.exited;
const u = p5.resourceUsage()!;
console.log("resourceUsage: maxRSS", u.maxRSS, "cpuTime.user", u.cpuTime.user, "typeof", typeof u.cpuTime.user);
onExit: 3 null undefined
resourceUsage: maxRSS 17764352 cpuTime.user 168246n typeof bigint
cpuTime の値は bigint で、単位はマイクロ秒です(公式ドキュメントの例では µs と表示しています)。
終わるまで待つ Bun.spawnSync
Bun.spawnSync は、子プロセスが終わるまで待ってから結果を返します。stdout と stderr は Buffer になり、終了コードが 0 かどうかを表す success が付きます(公式ドキュメントの、spawnSync を説明した節)。
const r = Bun.spawnSync(["sh", "-c", "echo out; echo err >&2; exit 2"]);
console.log("success:", r.success, "exitCode:", r.exitCode);
console.log("stdout:", r.stdout, JSON.stringify(r.stdout.toString()));
console.log("stderr:", JSON.stringify(r.stderr?.toString()));
const y = Bun.spawnSync(["yes"], { maxBuffer: 100 });
console.log("maxBuffer:", y.success, y.exitCode, y.signalCode, "stdout のバイト数:", y.stdout.length);
const tmo = Bun.spawnSync(["sleep", "5"], { timeout: 300 });
console.log("timeout:", tmo.success, tmo.exitCode, tmo.signalCode, tmo.exitedDueToTimeout);
success: false exitCode: 2
stdout: <Buffer 6f 75 74 0a> "out\n"
stderr: "err\n"
maxBuffer: false null SIGTERM stdout のバイト数: 65636
timeout: false null SIGTERM true
Bun.spawn と違って、何も指定しなくても stderr の中身("err\n")を受け取れました。maxBuffer は、出力がその量を超えたら子プロセスを止める指定です。100 バイトにしても、受け取った stdout は 65,636 バイトありました。公式ドキュメントには、超えたことに気づいた1回の読み込みのぶんだけ多くなることがある、と書かれています(公式ドキュメントの、maxBuffer を説明した節)。出力の大きさを正確に切りそろえる用途には使えません。タイムアウトで止まったときは、exitedDueToTimeout が true になりました。
spawnSync を待っている間は、ほかの処理が進みません。公式ドキュメントでも、HTTP サーバーやアプリには Bun.spawn、コマンドラインのツールには Bun.spawnSync が向く、とされています。
子の bun とメッセージをやりとりする
子プロセスも Bun で動かすときは、ipc を指定すると、親と子でメッセージを送り合えます。子では、Node.js の child_process.fork() と同じ process.send() と process.on("message") を使います(公式ドキュメントの、IPC を説明した節)。
// child.ts:親から受け取った数を2倍にして返す
process.on("message", (msg: any) => {
if (msg === "bye") process.exit(0);
process.send!({ doubled: msg.n * 2, from: "child" });
});
process.send!("ready");
// ipc.ts:親
const got: unknown[] = [];
const child = Bun.spawn(["bun", "child.ts"], {
ipc(message, proc) {
got.push(message);
console.log("親が受信:", JSON.stringify(message));
if (message === "ready") proc.send({ n: 21 });
else proc.send("bye");
},
});
console.log("子の終了コード:", await child.exited);
親が受信: "ready"
親が受信: {"doubled":42,"from":"child"}
子の終了コード: 0
オブジェクトもそのまま届きました。子を Node.js で動かすときは、serialization: "json" を指定する必要があると、公式ドキュメントに書かれています(Bun と Node.js の間の IPC の説明)。
起動にかかる時間は、1回あたり約0.9ミリ秒だった
何もせずに終わる /usr/bin/true を300回、1つずつ起動して終わるまで待ち、1回あたりの時間を測りました。Bun の Bun.spawn、Bun.spawnSync、Bun Shell の $、node:child_process の spawnSync と execFile(promisify したもの)を Bun で、node:child_process の2つを Node.js でも測っています。
import { spawnSync, execFile } from "node:child_process";
import { promisify } from "node:util";
const execFileP = promisify(execFile);
const N = 300;
const isBun = typeof Bun !== "undefined";
async function bench(label: string, fn: () => unknown) {
for (let i = 0; i < 10; i++) await fn(); // 慣らし
const t = performance.now();
for (let i = 0; i < N; i++) await fn();
const ms = performance.now() - t;
console.log(`${label}: ${N}回で ${ms.toFixed(0)}ms(1回あたり ${(ms / N).toFixed(2)}ms)`);
}
if (isBun) {
const { $ } = await import("bun");
await bench("Bun.spawn", async () => { await Bun.spawn(["/usr/bin/true"]).exited; });
await bench("Bun.spawnSync", () => Bun.spawnSync(["/usr/bin/true"]));
await bench("Bun Shell の $", () => $`/usr/bin/true`.quiet());
}
await bench(`child_process.spawnSync(${isBun ? "Bun" : "Node.js"})`, () => spawnSync("/usr/bin/true"));
await bench(`child_process.execFile(${isBun ? "Bun" : "Node.js"})`, () => execFileP("/usr/bin/true"));
// 並べて起動:sleep 0.5 を 4 つ
const t = performance.now();
await Promise.all([1, 2, 3, 4].map(() => (isBun ? Bun.spawn(["sleep", "0.5"]).exited : execFileP("sleep", ["0.5"]))));
console.log(`sleep 0.5 を4つ同時に: ${(performance.now() - t).toFixed(0)}ms`);
bun bench.ts と node bench.ts を3回ずつ実行した、1回あたりの時間です。
| 測ったもの | 1回目 | 2回目 | 3回目 |
|---|---|---|---|
Bun.spawn |
0.90ms | 0.83ms | 0.88ms |
Bun.spawnSync |
0.87ms | 0.86ms | 0.85ms |
Bun Shell の $ |
0.87ms | 1.03ms | 0.89ms |
Bun で child_process.spawnSync |
0.81ms | 1.00ms | 0.76ms |
Bun で child_process.execFile |
0.99ms | 1.09ms | 0.96ms |
Node.js で child_process.spawnSync |
1.84ms | 1.68ms | 1.68ms |
Node.js で child_process.execFile |
1.83ms | 1.67ms | 1.68ms |

Bun の中では、どの書き方も 0.76〜1.09 ミリ秒で、実行のたびのぶれのほうが、書き方による差より大きいくらいでした。Node.js の child_process は 1.67〜1.84 ミリ秒でした。同じ node:child_process のコードを Bun で動かすと、中央値で比べて spawnSync は約半分(0.81 と 1.68 ミリ秒)、execFile は約6割(0.99 と 1.68 ミリ秒)の時間で終わっています。
同じスクリプトの最後で、0.5秒かかる sleep 0.5 を4つ Promise.all で同時に起動したところ、Bun では3回とも502〜503ミリ秒で終わり、4つが並んで動きました。1つずつ待てば合わせて2秒かかる計算のところが、約0.5秒で終わっています。





