Skip to main content

Usage in Deno

import * as mod from "node:child_process";

The node:child_process module provides the ability to spawn subprocesses in a manner that is similar, but not identical, to popen(3). This capability is primarily provided by the spawn function:

import { spawn } from 'node:child_process';
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

By default, pipes for stdin, stdout, and stderr are established between the parent Node.js process and the spawned subprocess. These pipes have limited (and platform-specific) capacity. If the subprocess writes to stdout in excess of that limit without the output being captured, the subprocess blocks waiting for the pipe buffer to accept more data. This is identical to the behavior of pipes in the shell. Use the { stdio: 'ignore' } option if the output will not be consumed.

The command lookup is performed using the options.env.PATH environment variable if env is in the options object. Otherwise, process.env.PATH is used. If options.env is set without PATH, lookup on Unix is performed on a default search path search of /usr/bin:/bin (see your operating system's manual for execvpe/execvp), on Windows the current processes environment variable PATH is used.

On Windows, environment variables are case-insensitive. Node.js lexicographically sorts the env keys and uses the first one that case-insensitively matches. Only first (in lexicographic order) entry will be passed to the subprocess. This might lead to issues on Windows when passing objects to the env option that have multiple variants of the same key, such as PATH and Path.

The spawn method spawns the child process asynchronously, without blocking the Node.js event loop. The spawnSync function provides equivalent functionality in a synchronous manner that blocks the event loop until the spawned process either exits or is terminated.

For convenience, the node:child_process module provides a handful of synchronous and asynchronous alternatives to spawn and spawnSync. Each of these alternatives are implemented on top of spawn or spawnSync.

  • exec: spawns a shell and runs a command within that shell, passing the stdout and stderr to a callback function when complete.
  • execFile: similar to exec except that it spawns the command directly without first spawning a shell by default.
  • fork: spawns a new Node.js process and invokes a specified module with an IPC communication channel established that allows sending messages between parent and child.
  • execSync: a synchronous version of exec that will block the Node.js event loop.
  • execFileSync: a synchronous version of execFile that will block the Node.js event loop.

For certain use cases, such as automating shell scripts, the synchronous counterparts may be more convenient. In many cases, however, the synchronous methods can have significant impact on performance due to stalling the event loop while spawned processes complete.

Classes

Functions

f
exec

Spawns a shell then executes the command within that shell, buffering any generated output. The command string passed to the exec function is processed directly by the shell and special characters (vary based on shell) need to be dealt with accordingly:

    f
    execFile

    The child_process.execFile() function is similar to exec except that it does not spawn a shell by default. Rather, the specified executable file is spawned directly as a new process making it slightly more efficient than exec.

      f
      execFileSync

      The child_process.execFileSync() method is generally identical to execFile with the exception that the method will not return until the child process has fully closed. When a timeout has been encountered and killSignal is sent, the method won't return until the process has completely exited.

        f
        execSync

        The child_process.execSync() method is generally identical to exec with the exception that the method will not return until the child process has fully closed. When a timeout has been encountered and killSignal is sent, the method won't return until the process has completely exited. If the child process intercepts and handles the SIGTERM signal and doesn't exit, the parent process will wait until the child process has exited.

          f
          fork

          The child_process.fork() method is a special case of spawn used specifically to spawn new Node.js processes. Like spawn, a ChildProcess object is returned. The returned ChildProcess will have an additional communication channel built-in that allows messages to be passed back and forth between the parent and child. See subprocess.send() for details.

            f
            spawn

            The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

              f
              spawnSync

              The child_process.spawnSync() method is generally identical to spawn with the exception that the function will not return until the child process has fully closed. When a timeout has been encountered and killSignal is sent, the method won't return until the process has completely exited. If the process intercepts and handles the SIGTERM signal and doesn't exit, the parent process will wait until the child process has exited.

                Interfaces

                I
                CommonOptions
                No documentation available
                I
                I
                ExecFileSyncOptions
                No documentation available
                I
                ExecOptionsWithBufferEncoding
                No documentation available
                I
                ExecOptionsWithStringEncoding
                No documentation available
                I
                ExecSyncOptions
                No documentation available
                I
                MessageOptions
                No documentation available
                I
                ProcessEnvOptions
                No documentation available
                I
                PromiseWithChild
                No documentation available
                I
                SpawnOptions
                No documentation available
                I
                SpawnOptionsWithoutStdio
                No documentation available
                I
                SpawnOptionsWithStdioTuple
                No documentation available
                I
                SpawnSyncOptions
                No documentation available

                Type Aliases

                T
                ExecFileException
                No documentation available
                  T
                  IOType
                  No documentation available
                    T
                    SendHandle
                    No documentation available
                      T
                      Serializable
                      No documentation available
                        T
                        SerializationType
                        No documentation available
                          T
                          StdioNull
                          No documentation available
                            T
                            StdioOptions
                            No documentation available
                              T
                              StdioPipe
                              No documentation available
                                T
                                StdioPipeNamed
                                No documentation available
                                  Back to top