execa

Process execution for humans

weekly downloads114.3M

versionv9.6.1

licenseMIT

categorytoolchain

execchildprocesssubprocessexecuteforkexecfilespawnfileshellbinbinarybinariesnpmpathlocalzx

Overview

Execa is a widely-adopted Node.js package that wraps the built-in child_process module with a modern, promise-based API. With over 114 million weekly downloads, it has become the de facto standard for executing external commands, scripts, and binaries in JavaScript applications. Unlike the native child_process methods, execa eliminates common pain points like manual output buffering, inconsistent error handling, and platform-specific quirks.

The package was created to address the gap between Node.js's low-level process APIs (designed for maximum flexibility) and what developers actually need for typical use cases: running commands, capturing output, handling errors gracefully, and piping data between processes. Execa automatically handles argument escaping to prevent shell injection vulnerabilities, strips trailing newlines from output, and provides significantly better Windows support including proper shebang handling and graceful termination.

Developers choose execa when building CLI tools, automation scripts, build systems, testing frameworks, and any application that needs to spawn child processes reliably. Its promise-based interface integrates seamlessly with async/await syntax, and advanced features like IPC messaging, stream transformation, and multi-process piping make it suitable for both simple command execution and complex process orchestration. As of version 6, execa is a pure ESM package, aligning with modern JavaScript standards.

The package is particularly valuable in cross-platform applications where consistent behavior across operating systems is critical. Its automatic cleanup mechanisms prevent zombie processes, and the rich error objects include complete context (command, exit code, stderr output) making debugging straightforward. For teams maintaining large codebases, execa's extensive TypeScript types and predictable API reduce cognitive load compared to working directly with child_process.

Quick Start

typescript

import { execa, $ } from 'execa';

// Basic command execution with promise handling
const { stdout, exitCode } = await execa('git', ['log', '--oneline', '-n', '5']);
console.log(`Last 5 commits:\n${stdout}`);

// Template literal syntax ($ is optional, requires configuration)
const { stdout: nodeVersion } = await $`node --version`;
console.log('Node version:', nodeVersion);

// Execute local npm binaries without npx
const { stdout: eslintOutput } = await execa('eslint', ['src/**/*.js'], {
  cwd: process.cwd(),
  preferLocal: true
});

// Pipe commands together and capture intermediate results
const pipeline = execa('cat', ['large-file.txt'])
  .pipe(execa('grep', ['ERROR']))
  .pipe(execa('wc', ['-l']));
const { stdout: errorCount } = await pipeline;
console.log(`Found ${errorCount} error lines`);

// Stream processing with error handling
try {
  const subprocess = execa('ffmpeg', [
    '-i', 'input.mp4',
    '-c:v', 'libx264',
    'output.mp4'
  ]);
  
  subprocess.stdout.on('data', (chunk) => {
    console.log('Progress:', chunk.toString());
  });
  
  await subprocess;
} catch (error) {
  console.error('Command failed:', error.command);
  console.error('Exit code:', error.exitCode);
  console.error('Stderr:', error.stderr);
}

// IPC communication with a child process
const child = execa('node', ['worker.js'], {
  ipc: true
});

child.on('message', (message) => {
  console.log('Received from child:', message);
});

child.send({ task: 'process', data: [1, 2, 3] });
await child;

Use Cases

Building CLI tools and task runners - Execute external binaries, Git commands, or locally-installed npm packages without requiring npx. Execa makes it simple to run build tools, linters, or formatters programmatically and handle their output.

Automation and deployment scripts - Run sequences of shell commands with proper error handling and logging. Capture command output for validation, pipe data between processes, or redirect output to files for audit trails.

Testing frameworks and CI/CD pipelines - Spawn test processes, execute commands against containerized environments, or run integration tests that require external services. The promise-based API integrates cleanly with test assertions.

File processing and data transformation pipelines - Stream large files through external programs (like ffmpeg, imagemagick, or compression tools) using pipe operations, transform output on-the-fly with generator functions, and handle backpressure automatically.

Process monitoring and management tools - Launch long-running services, establish IPC communication channels for message passing, monitor process health through stdout/stderr streams, and ensure proper cleanup when parent processes terminate.

Pros & Cons

Pros

+Promise-based API with async/await support eliminates callback complexity and integrates seamlessly with modern JavaScript
+Automatic argument escaping prevents shell injection vulnerabilities without requiring manual sanitization
+Superior cross-platform support handles Windows quirks (PATHEXT, shebangs, termination) that cause failures with native child_process
+Rich error objects with complete context (command, exit code, stderr, stdout) make debugging failures straightforward
+Advanced features like IPC, stream transformation, and multi-process piping enable complex process orchestration
+Higher default buffer limits (100MB vs 1MB) prevent truncation issues with commands producing substantial output

Cons

−Pure ESM package since v6 requires ES module support and may complicate integration in CommonJS-only projects
−Additional dependency adds ~50KB to bundle size, which may matter for serverless or edge deployments with tight size constraints
−Template literal syntax ($`command`) while convenient, can be less explicit than function calls for some teams preferring clear argument separation
−Learning curve for advanced features (stream transformation, IPC) requires understanding Node.js streams and child process concepts
−No built-in retry logic or timeout handling requires wrapping execa calls with additional error handling code

Comparisons

execa vs cross-env

toolchain

Install

bash

npm install execa

bash

pnpm add execa

bash

bun add execa

Overview

Quick Start

typescript

import { execa, $ } from 'execa';

// Basic command execution with promise handling
const { stdout, exitCode } = await execa('git', ['log', '--oneline', '-n', '5']);
console.log(`Last 5 commits:\n${stdout}`);

// Template literal syntax ($ is optional, requires configuration)
const { stdout: nodeVersion } = await $`node --version`;
console.log('Node version:', nodeVersion);

// Execute local npm binaries without npx
const { stdout: eslintOutput } = await execa('eslint', ['src/**/*.js'], {
  cwd: process.cwd(),
  preferLocal: true
});

// Pipe commands together and capture intermediate results
const pipeline = execa('cat', ['large-file.txt'])
  .pipe(execa('grep', ['ERROR']))
  .pipe(execa('wc', ['-l']));
const { stdout: errorCount } = await pipeline;
console.log(`Found ${errorCount} error lines`);

// Stream processing with error handling
try {
  const subprocess = execa('ffmpeg', [
    '-i', 'input.mp4',
    '-c:v', 'libx264',
    'output.mp4'
  ]);
  
  subprocess.stdout.on('data', (chunk) => {
    console.log('Progress:', chunk.toString());
  });
  
  await subprocess;
} catch (error) {
  console.error('Command failed:', error.command);
  console.error('Exit code:', error.exitCode);
  console.error('Stderr:', error.stderr);
}

// IPC communication with a child process
const child = execa('node', ['worker.js'], {
  ipc: true
});

child.on('message', (message) => {
  console.log('Received from child:', message);
});

child.send({ task: 'process', data: [1, 2, 3] });
await child;

Use Cases

Pros & Cons

Pros

+Promise-based API with async/await support eliminates callback complexity and integrates seamlessly with modern JavaScript
+Automatic argument escaping prevents shell injection vulnerabilities without requiring manual sanitization
+Superior cross-platform support handles Windows quirks (PATHEXT, shebangs, termination) that cause failures with native child_process
+Rich error objects with complete context (command, exit code, stderr, stdout) make debugging failures straightforward
+Advanced features like IPC, stream transformation, and multi-process piping enable complex process orchestration
+Higher default buffer limits (100MB vs 1MB) prevent truncation issues with commands producing substantial output

Cons

−Pure ESM package since v6 requires ES module support and may complicate integration in CommonJS-only projects
−Additional dependency adds ~50KB to bundle size, which may matter for serverless or edge deployments with tight size constraints
−Template literal syntax ($`command`) while convenient, can be less explicit than function calls for some teams preferring clear argument separation
−Learning curve for advanced features (stream transformation, IPC) requires understanding Node.js streams and child process concepts
−No built-in retry logic or timeout handling requires wrapping execa calls with additional error handling code