child_process

Running shell commands and spawning processes from Node.js — exec, spawn, execFile, fork, and handling output.

What it is, in plain English: The child_process module lets Node.js spawn external processes. exec() runs a shell command and buffers the output — good for short commands. spawn() runs a command with streaming output — good for long-running processes. execFile() runs an executable directly (no shell — safer and faster). fork() spawns a new Node.js process and sets up message-passing between parent and child.

Where this bites you

exec() collects a command's entire output in memory and gives up past maxBuffer, which is 1 MB by default. A command that prints more than that, such as a long git log, a database dump or a verbose build, is killed and the call fails with ERR_CHILD_PROCESS_STDIO_MAXBUFFER. It works in testing with small output, then fails in production with real data.

import { exec } from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);

// a command with a lot of output -- here 2 MB, like a big `git log` or a database dump
try {
  const { stdout } = await execAsync(`node -e "process.stdout.write('x'.repeat(2_000_000))"`);
  console.log("got", stdout.length, "bytes");
} catch (e) {
  console.log(e.code, "|", e.message);
}
// ERR_CHILD_PROCESS_STDIO_MAXBUFFER | stdout maxBuffer length exceeded

Running commands from Node.js

exec — run a shell command

import { exec }   from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);

// Run a git command:
const { stdout, stderr } = await execAsync("git log --oneline -5");
console.log(stdout);  // last 5 commits

// Check Node.js version:
const { stdout: version } = await execAsync("node --version");
console.log(version.trim());  // "v20.15.0"

// Handle errors:
try {
  await execAsync("ls /nonexistent");
} catch (e) {
  console.error("Command failed:", e.message);
  console.error("Exit code:", e.code);     // e.g. 2
  console.error("Stderr:", e.stderr);
}

Use exec() for commands with small, predictable output, like the version check above. For anything that can grow, use spawn() (next section), which streams the output in chunks with no size limit. If you really need it all as one string, you can raise the limit with exec(cmd, { maxBuffer: 50 * 1024 * 1024 }), but that just moves the cliff.

import { spawn } from "child_process";

// spawn streams the output instead of collecting it into one buffer:
const child = spawn("node", ["-e", "process.stdout.write('x'.repeat(2_000_000))"]);
let bytes = 0;
child.stdout.on("data", (chunk) => { bytes += chunk.length; });   // process as it arrives
child.on("close", (code) => console.log("exit", code, "| got", bytes, "bytes"));
// exit 0 | got 2000000 bytes

spawn — streaming output for long commands

import { spawn } from "child_process";

// Good for: npm install, build tools, long-running processes
const install = spawn("npm", ["install"], {
  cwd:   "./my-project",  // working directory
  stdio: "pipe",          // capture stdout/stderr (default)
});

install.stdout.on("data", (chunk) => process.stdout.write(chunk));
install.stderr.on("data", (chunk) => process.stderr.write(chunk));

install.on("close", (code) => {
  if (code === 0) console.log("Install successful!");
  else            console.error(`Install failed with code ${code}`);
});

// Kill a process:
const proc = spawn("long-running-command");
setTimeout(() => proc.kill("SIGTERM"), 10000);  // kill after 10s

Shell injection risk. Never pass user input directly to exec() — it goes through the shell. Use execFile() or spawn() with an args array instead.

Try It Yourself

// child_process — run shell commands from Node.js
// import { exec, spawn, execFile, fork } from "child_process";
// import { promisify } from "util";
// const execAsync = promisify(exec);

// The four main functions:
const FUNCTIONS = {
  exec: {
    desc: "Run a shell command, buffer all output",
    use:  "Short commands (git status, ls, npm run)",
    code: `
const { stdout, stderr } = await execAsync("git log --oneline -5");
console.log(stdout);  // last 5 commits`,
  },
  execFile: {
    desc: "Run an executable directly (no shell)",
    use:  "Safer than exec, can't use shell features (&&, |)",
    code: `
const { stdout } = await execFileAsync("node", ["--version"]);
console.log(stdout.trim());  // "v20.0.0"`,
  },
  spawn: {
    desc: "Stream output as it arrives — for long-running processes",
    use:  "Build tools, compilers, video encoding",
    code: `
const proc = spawn("npm", ["install"]);
proc.stdout.on("data", chunk => process.stdout.write(chunk));
proc.on("close", code => console.log("Exit code:", code));`,
  },
  fork: {
    desc: "Spawn a new Node.js process with IPC",
    use:  "Offload CPU work to a child Node.js process",
    code: `
// parent.js:
const child = fork("worker.js");
child.send({ task: "compute", n: 40 });
child.on("message", (result) => console.log("Result:", result));

// worker.js:
process.on("message", ({ task, n }) => {
  if (task === "compute") process.send(fibonacci(n));
});`,
  },
};

Object.entries(FUNCTIONS).forEach(([fn, info]) => {
  console.log(`\n${fn.toUpperCase()}`);
  console.log(`  What: ${info.desc}`);
  console.log(`  Use:  ${info.use}`);
});

// SECURITY: NEVER pass user input directly to exec/spawn without sanitisation:
// const dangerous = exec(\`ls \${userInput}\`);  // ← shell injection!
// Safe: use execFile with args array:
// execFile("ls", [userInput]);  // args passed as array, no shell expansion

fork, execFile, and advanced patterns

// fork — spawn a child Node.js process with IPC (message-passing):
import { fork } from "child_process";

// parent.js:
const child = fork("./worker.js", [], { silent: true });

child.send({ task: "fibonacci", n: 45 });

child.on("message", (result) => {
  console.log("Result:", result.value);  // fast — computed in separate process
  child.kill();
});

child.on("error", (e) => console.error("Worker error:", e));

// worker.js (in a separate file):
// process.on("message", ({ task, n }) => {
//   if (task === "fibonacci") {
//     const value = fib(n);
//     process.send({ value });
//   }
// });

// execFile — run a specific executable safely:
import { execFile } from "child_process";
const execFileAsync = promisify(execFile);

// Run a Python script:
const { stdout } = await execFileAsync("python3", ["script.py", "--input", "data.csv"]);
console.log(stdout);

// Send stdin to a process:
const proc = spawn("cat");  // cat echoes stdin to stdout
proc.stdin.write("Hello from Node.js!\n");
proc.stdin.end();
proc.stdout.on("data", (d) => console.log(d.toString()));

execa — the better child_process (npm)

// npm install execa — nicer API with Promises and streams:
import { execa } from "execa";

// Simple command:
const { stdout } = await execa("git", ["log", "--oneline", "-5"]);

// Pipe between processes:
const { stdout: sorted } = await execa("sort", { inputFile: "names.txt" });

// Stream output:
const proc = execa("npm", ["run", "build"]);
proc.stdout.pipe(process.stdout);
await proc;

Process lifecycle, IPC protocol, and security

// Detached process — runs after parent exits:
const child = spawn("long-task", ["--background"], {
  detached: true,
  stdio:    "ignore",  // don't inherit parent's stdio
});
child.unref();  // parent can exit without waiting for child

// Shared stdio (inherit) — child uses parent's terminal:
spawn("vim", ["file.txt"], { stdio: "inherit" });

// Environment variables for child:
spawn("node", ["app.js"], {
  env: {
    ...process.env,         // inherit parent's env
    NODE_ENV: "production", // override/add specific vars
    PORT:     "8080",
  }
});

// IPC protocol (fork) — messages are serialised to JSON:
// Only: strings, numbers, booleans, null, arrays, plain objects
// NOT: functions, Dates, Sets, Maps, Buffers or typed arrays (they arrive as plain objects)
// fork(file, [], { serialization: "advanced" }) keeps typed arrays, Dates, Maps and Sets

// Bidirectional communication pattern:
const worker = fork("./worker.js");
const pending = new Map();
let requestId = 0;

function callWorker(method, args) {
  return new Promise((resolve, reject) => {
    const id = requestId++;
    pending.set(id, { resolve, reject });
    worker.send({ id, method, args });
  });
}

worker.on("message", ({ id, result, error }) => {
  const { resolve, reject } = pending.get(id) ?? {};
  pending.delete(id);
  error ? reject(new Error(error)) : resolve(result);
});

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.