nodejs / nodejs/node

child_process: add cross-platform subprocess.killTree([signal])

Open
#64,406 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

child_process
Dominant language
JavaScript
Stars
122k
Forks
37.3k
Avg merge
4d 2h
Merged PRs (30d)
283

Description

What is the problem this feature will solve?

subprocess.kill([signal]) only targets the direct child PID. Descendants often keep running, especially when:

  • shell: true (shell exits, real command survives)
  • the child is a build driver (bash / make / ninja) that spawns grandchildren
  • on Windows, where POSIX signals are not real and kill() does not terminate a process tree

Userland workarounds are fragmented and OS-specific:

  • Unix: detached: true + process.kill(-pid, signal) (process group; not always applicable)
  • Windows: taskkill /pid <pid> /T /F (or equivalent)
  • npm packages such as tree-kill

This comes up often for Ctrl+C / timeout cleanup in CLIs and build orchestrators.

Related prior request (closed stale): https://github.com/nodejs/node/issues/40438 (killDeep).

What is the feature you are proposing to solve the problem?

Add an explicit, documented API, for example:

subprocess.killTree([signal]);
// and/or
child_process.killTree(pid[, signal]);

Goals:

  1. Cross-platform: one call that best-effort terminates the process and its descendants on Windows, Linux, and macOS.
  2. Clear semantics vs kill(): kill() stays single-PID; killTree() is the tree variant.
  3. Document limitations: PID reuse races, process-group vs true tree walk, signal mapping on Windows (where signals are not POSIX).

A reasonable Windows implementation can use the platform tree-terminate facility (today: taskkill /T); Unix can use process-group kill when the child is a group leader, otherwise a documented tree walk.

What alternatives have you considered?
  • Keep using tree-kill / ad-hoc taskkill in every project
  • Rely on detached + negative PID (Unix-only, requires spawn options up front)
  • Expand subprocess.kill() to kill trees (breaking / surprising; prefer a separate killTree name)

Naming killTree (rather than overloading kill) makes the stronger, OS-dependent behavior opt-in and discoverable.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the child_process subprocess.kill API and compare the Unix process-group approach with Windows taskkill /T /F described in the issue. Define the cross-platform killTree semantics, signal mapping, and documented limitations, then verify behavior on Windows, Linux, and macOS.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
api, operating-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.