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.
import { spawn } from 'node:child_process'; const child = spawn(process.execPath, ['service.js'], { detached: true, stdio: 'ignore', }); child.unref();
Try it
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.
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 defaultstdiothe parent still has open streams to the child, which keep it alive. Use'ignore', file descriptors, or callunref()on those streams too.detachedalone does not let the parent exit. Withoutunref()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. Plainchild.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.