Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท child_process, worker_threads and cluster

Node.js detached child processes

How detached child processes work in Node.js: the detached option, unref(), stdio rules, process groups on Unix, killing a whole group and Windows differences.

Normally a child process is tied to its parent: the parent waits for it before exiting, and on a terminal the child receives the same Ctrl+C as the parent. Setting detached: true in the options of spawn() breaks that tie so the child can keep running after the parent has finished. It is how a launcher starts a background service, a daemon-like helper, or a long task that must survive its starter.

Detaching has two halves. detached: true changes how the operating system treats the child (on Unix it becomes the leader of a new session and process group; on Windows it gets its own console window unless hidden). child.unref() changes how Node.js treats it: the parent's event loop no longer waits for the child. You normally need both, plus a stdio setting that does not tie the two together.

NODE
import { spawn } from 'node:child_process';

const child = spawn(process.execPath, ['service.js'], {
  detached: true,
  stdio: 'ignore',
});
child.unref();

Try it

Node.js A child that finishes after the parent let go

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Killing a whole process group (Unix)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Options in detail

Setting Effect
detached: true (Unix) The child calls setsid(): new session, new process group whose id equals the child's pid, no controlling terminal. Terminal signals (Ctrl+C) sent to the parent's group do not reach it.
detached: true (Windows) The child gets its own console window, and it can outlive the parent. Add windowsHide: true to hide the window.
child.unref() Removes the child (and its pipes) from the set of things that keep the parent's event loop running. Call child.ref() to undo it.
stdio: 'ignore' The usual companion. No pipes means nothing connects the processes.
stdio: ['ignore', fd, fd] Send output of a long-lived child to a log file opened with fs.openSync(path, 'a').

Usage notes

  • unref() alone is not enough while pipes are open. With default stdio the parent still has open streams to the child, which keep it alive. Use 'ignore', file descriptors, or call unref() on those streams too.
  • detached alone does not let the parent exit. Without unref() the parent still waits for the child to end.
  • Signals to a group. On Unix, process.kill(-pid, signal) signals every process in the child's group, including grandchildren it started. Plain child.kill() only signals the child itself and leaves grandchildren running.
  • The child can still die with the terminal. A detached child has no controlling terminal, but if it writes to a closed pipe it receives SIGPIPE. Redirect its output to files or 'ignore'.
  • Windows has no process groups like Unix. Negative pids do not work; to stop a tree use taskkill /pid <pid> /T /F.
  • Orphans need management. A detached process that nobody tracks keeps running until it ends or is killed. Store its pid (for example in a file) so a later run can stop it.
  • Not a service manager. For production daemons use systemd, a container or a process manager that restarts crashed processes; a detached child is a one-shot technique.