child_process

child_process runs external programs from Node - prefer spawn with explicit argument arrays, understand stdio modes, and avoid shell injection when wrapping CLI tools.

Recipe

import { spawn } from 'node:child_process';
 
const child = spawn('git', ['rev-parse', 'HEAD'], { stdio: ['ignore', 'pipe', 'pipe'] });

import { promisify } from 'node:util';
import { execFile } from 'node:child_process';
 
const execFileAsync = promisify(execFile);
const { stdout } = await execFileAsync('node', ['--version']);

When to reach for this:

• Image processing via ffmpeg CLI
• Git operations in deployment scripts
• Running language formatters in pre-commit hooks
• Isolating untrusted code in separate OS process (with sandbox beyond Node)

Working Example

import { spawn } from 'node:child_process';
import { once } from 'node:events';
 
async function runGitHash(): Promise<string> {
  const child = spawn('git', ['rev-parse', 'HEAD'], {
    stdio: ['ignore', 'pipe', 'pipe'],
  });
 
  let stdout = '';
  child.stdout.on('data', (chunk: Buffer) => {
    stdout += chunk.toString('utf8');
  });
 
  const [code] = await once(child, 'exit');
  if (code !== 0) throw new Error(`git exited ${code}`);
  return stdout.trim();
}
 
// Dangerous - do not do this with user input:
// spawn(`git rev-parse ${userBranch}`, { shell: true });

import { pipeline } from 'node:stream/promises';
import { spawn } from 'node:child_process';
import { createWriteStream } from 'node:fs';
 
async function compressWithGzip(input: string, output: string): Promise<void> {
  const gzip = spawn('gzip', ['-c', input], { stdio: ['ignore', 'pipe', 'inherit'] });
  await pipeline(gzip.stdout, createWriteStream(output));
  const code = await new Promise<number>((res) => gzip.on('exit', res));
  if (code !== 0) throw new Error(`gzip failed ${code}`);
}

What this demonstrates:

• Argument array passes literals to execve without shell interpretation
• Collect stdout via stream chunks - not exec buffer limits for large output
• Pipe child stdout to file with pipeline for backpressure
• shell: true only for trusted fixed commands - never with user strings

Deep Dive

How It Works

• spawn - streams stdio, returns immediately, exit event with code.
• exec - buffers stdout/stderr, invokes shell by default - injection risk.
• execFile - no shell, buffered output with maxBuffer default 1MB.
• fork - special Node child with IPC channel - legacy pattern before worker_threads.

API Comparison

TypeScript Notes

import type { ChildProcess } from 'node:child_process';
 
export function killProcessTree(child: ChildProcess): void {
  if (child.pid) process.kill(-child.pid, 'SIGTERM');
}

Platform-specific - Linux process groups need detached: true on spawn.

Gotchas

• shell: true + user input - command injection. Fix: spawn(cmd, [arg1, arg2]) without shell.
• exec maxBuffer exceeded - throws on large stdout. Fix: spawn with streams.
• Not reaping zombies - always attach exit handler or await exit in long-running supervisors.
• Inherited stdio in daemons - child holds TTY open. Fix: stdio: 'ignore' for background jobs.
• Windows path quoting - still use array form; avoid manual quote escaping in shell strings.

Alternatives

FAQs

Related

• worker_threads - in-process CPU
• Process Signals & Shutdown - killing children cleanly
• Processes Best Practices - security checklist
• Callbacks vs Promises Migration - promisify execFile

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.