Skip to main content
headless-reaper: a headless browser window crossed out

headless-reaper

한국어

A command-line tool that finds and stops orphaned headless browsers, with a dry run by default.

Python 3.9+ · Rust

pypi license

On macOS the Rust edition scans in 11.3 ms and starts in 2.9 ms; the Python edition takes 122.1 ms and 36.1 ms, from the saved 20-run measurement.

Install · Quick start · Why

A disposable orphan browser is listed, reaped, and absent from the final scan

The demo starts a dedicated headless shell from a short-lived parent, then reaps that browser's /tmp profile. It never launches Google Chrome. Recording source.

Install

pipx install headless-reaper
uv tool install headless-reaper
pip install headless-reaper

Python 3.9+. Wheels install the Rust CLI and an importable Python reference. Source installs need Rust; cargo install --path rust --locked installs the standalone command.

Platform Observed behavior
macOS arm64 Orphan detection and cleanup; live-parent browser preserved
Ubuntu 24.04 arm64 Chromium and Firefox orphan cleanup; live-parent browser preserved
Windows x64 Both editions exit 2: browser reaping is unsupported

Quick start

Start with a dry run. These outputs came from a disposable headless-shell process. The environment variable limits every command to that one profile; replace the path with your own job's profile directory.

$ export HEADLESS_REAPER_PATH=/tmp/reaper-demo.58q834un
$ headless-reaper
headless-reaper 0.1.0: 1 orphaned group, 4 processes, 224.8 MB RSS (1024 processes scanned, paths /tmp/reaper-demo.58q834un)

ROOT   AGE  RSS       PIDS  PROFILE
18952  1s   224.8 MB  4     /tmp/reaper-demo.58q834un
       why: headless, temp profile, remote debugging; launcher gone (reparented to launchd 1)

dry run: nothing was killed. Rerun with --kill to terminate these groups.
$ headless-reaper --kill
headless-reaper 0.1.0: 1 orphaned group, 4 processes, 224.8 MB RSS (1024 processes scanned, paths /tmp/reaper-demo.58q834un)

ROOT   AGE  RSS       PIDS  PROFILE
18952  1s   224.8 MB  4     /tmp/reaper-demo.58q834un
       why: headless, temp profile, remote debugging; launcher gone (reparented to launchd 1)

reaped 1 group: sent SIGTERM to 4 of 4 processes, SIGKILL to 0.
$ headless-reaper
headless-reaper 0.1.0: no orphaned headless browsers (1024 processes scanned, paths /tmp/reaper-demo.58q834un).

The second scan confirms that the scoped browser is gone. Process counts, PIDs and RSS will differ on your machine.

Why

A crashed test can leave its browser running after the test process is gone. You can find it with ps, but deciding which helpers belong to it takes another step. headless-reaper groups the browser tree and checks whether its launcher still exists before proposing cleanup.

Use your test framework's browser-close call for normal teardown. Use ps or a process monitor when you need to inspect arbitrary processes. This tool handles leftovers: it requires a recognized browser, an automation signal, and a missing launcher. A default personal profile is excluded.

Measurements

Saved measurements from 2026-11-17: median of 20 sequential subprocess runs, warm filesystem cache, release Rust 1.100.0. Startup ran --version; scanning ran --json --path /tmp/headless-reaper-bench-empty and still read the whole process table. Peak RSS came from a separate /usr/bin/time scan. These are two hosts and their process populations, not a claim about every machine.

Platform / edition Startup (ms) Scan (ms) Peak RSS (KiB)
macOS arm64 / Python 3.12.8 36.078 122.098 23,296
macOS arm64 / Rust 2.856 11.315 3,136
Ubuntu 24.04 arm64 / Python 3.12 68.953 76.615 15,144
Ubuntu 24.04 arm64 / Rust 0.841 5.564 1,892

Reference

Option Default Meaning
--kill Off SIGTERM, wait, then SIGKILL for surviving targets
--path PREFIX All profiles Limit profile paths; repeat for several prefixes
--min-age DURATION 0 Skip younger groups; accepts 30s, 10m, 2h, 1d, up to 100 years
--grace DURATION 10s Wait between SIGTERM and SIGKILL
--remove-profiles Off With --kill, remove eligible temporary profiles
--json Off Report groups, totals, cleanup results and errors as JSON
--clean-clones Off Inspect unused macOS code-signing clones; add --kill to delete
--all-leftovers Off Combine --kill, --clean-clones and --remove-profiles

A duration above 100 years is a usage error in --min-age and --grace.

Exit 0 means a dry run succeeded or all targets were reaped. Exit 1 means a target survived or inspection failed. Exit 2 means invalid usage or an unsupported platform.

HEADLESS_REAPER_PATH, HEADLESS_REAPER_MIN_AGE, and HEADLESS_REAPER_GRACE set defaults. Paths use : as the separator on macOS/Linux. Flags override environment values. There is no configuration file.

Target selection

Select an eligible browser, report it, and terminate only when --kill is requested

An eligible target is a recognized automation browser whose launcher is gone and whose path and age match your scope. Personal default profiles are excluded. KILL is only for processes surviving the grace period.

A root must be a recognized Chrome/Chromium, Edge, Firefox, or WebKit browser process, not a renderer or helper. It must carry --headless, a temporary or automation profile, or remote debugging together with such a profile. Its parent must be PID 1, an init process, or missing from the snapshot.

The tool groups descendants under the root. Before signalling, it compares process start times to avoid signalling a recycled PID. It excludes default personal profiles and browsers whose launcher is alive.

Profile and clone cleanup

--remove-profiles requires --kill. Cleanup preserves a profile outside temporary roots, a shared temp root itself such as /tmp, one still used by a live browser, one with a live singleton lock, or one whose group left a survivor.

On macOS, --clean-clones examines recognized browser code_sign_clone.* directories under the current user's X temp directory. It uses a ten-minute minimum age unless you set one. Directory symlinks and live uses are preserved; matching includes device/inode identity because clones may share hard links. An open-file scan failure prevents deletion.

Clone reports distinguish apparent size, allocated blocks, and observed free-space change. Shared APFS blocks mean apparent size is not reclaimable space. --path filters browser profiles; it does not change the fixed clone scope. Clone-only mode does nothing on other operating systems.

Python

import time
from headless_reaper import find_groups, list_processes

groups = find_groups(list_processes(), now=time.time(),
                     min_age=600, paths=("/tmp/my-test",))
for group in groups:
    print(group.root.pid, group.profile, group.rss_bytes())

reap(groups) terminates selected groups; cleanup_profiles(groups) handles their temporary profiles. clean_clones(kill=False, min_age=600) performs a macOS clone dry run. python -m headless_reaper selects the Python CLI explicitly.

Limits

  • A browser launched directly by launchd or systemd looks orphaned. Scope cleanup with --path; an age threshold alone does not establish ownership.
  • WebKit's argument detection was checked, but a live WebKit browser was not exercised because the test host lacked GTK 4.
  • macOS/Linux x86_64 backends were not exercised. Windows has no browser backend.
  • The Python macOS backend reads ps output and cannot recover profile paths containing spaces reliably. Rust reads exact argv through KERN_PROCARGS2; Linux reads /proc in both editions.
  • A visible automation browser with a custom home-directory profile can remain after its launcher exits. The detector does not treat every remote-debugging browser as disposable.

Contributing

Issues and platform reports are welcome; run cargo test --manifest-path rust/Cargo.toml from the source checkout. See CONTRIBUTING.md for every check and the review process, and AGENTS.md for the code layout and safety rules.

License

MIT. See LICENSE.

Unofficial; not affiliated with Google, Mozilla, Microsoft, or the browser automation projects mentioned here.

Metadata

Release files for headless-reaper 0.1.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for headless-reaper 0.1.5
File Size Uploaded Provenance Actions
headless_reaper-0.1.5.tar.gz 44.9 kB Without provenance Details for headless_reaper-0.1.5.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for headless-reaper 0.1.5
File Actions
headless_reaper-0.1.5-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for headless_reaper-0.1.5-py3-none-win_amd64.whl
headless_reaper-0.1.5-py3-none-manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.28+ x86-64 Details for headless_reaper-0.1.5-py3-none-manylinux_2_28_x86_64.whl
headless_reaper-0.1.5-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for headless_reaper-0.1.5-py3-none-manylinux_2_28_aarch64.whl
headless_reaper-0.1.5-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for headless_reaper-0.1.5-py3-none-macosx_11_0_arm64.whl
headless_reaper-0.1.5-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for headless_reaper-0.1.5-py3-none-macosx_10_12_x86_64.whl

Total release size: 1.6 MB

Release files / headless_reaper-0.1.5.tar.gz

Download URL headless_reaper-0.1.5.tar.gz
Size 44.9 kB
Tags Source
SHA-256 checksum
How to use checksums
8b675f05bbfd482208f161dad0dd9bc0041572bd633d057232f29007853c2368
BLAKE2b-256 checksum
How to use checksums
d10af3ff8018ff84b163e1bd3b2bb9b1e4df7be853b639b2818c53e8fe1d5203
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / headless_reaper-0.1.5-py3-none-win_amd64.whl

Download URL headless_reaper-0.1.5-py3-none-win_amd64.whl
Size 192.8 kB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
5a4cea13db10343e8d6baf70e0323ba36b08ebc4885c0f77737646c3b6bd58f8
BLAKE2b-256 checksum
How to use checksums
f8371bc4b6272e1c8ea8d519d92dcb10a4ca98576bf5f9cbe408821d4b424438
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / headless_reaper-0.1.5-py3-none-manylinux_2_28_x86_64.whl

Download URL headless_reaper-0.1.5-py3-none-manylinux_2_28_x86_64.whl
Size 344.8 kB
Tags Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
d44102e2903abbcb84df97da952292b916aa8050f42bd6e649b9982378a59a31
BLAKE2b-256 checksum
How to use checksums
646ca1e629753447d181ecc149f0a24f4c9e2b5b791be538ecf212e3d5d87bf4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / headless_reaper-0.1.5-py3-none-manylinux_2_28_aarch64.whl

Download URL headless_reaper-0.1.5-py3-none-manylinux_2_28_aarch64.whl
Size 326.4 kB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
06086be9b641d2aa392ab7a8d99f2d57911cc0d94f93bb667dcdf1fedb48ea8d
BLAKE2b-256 checksum
How to use checksums
9779c3975cc47b6e7bbd86577f1cb72479b7e0e959c445585d538ea604d17e7f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / headless_reaper-0.1.5-py3-none-macosx_11_0_arm64.whl

Download URL headless_reaper-0.1.5-py3-none-macosx_11_0_arm64.whl
Size 346.4 kB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
7d01e5c8650089ff9614e72f691f8746137d4bbdd86baeae7d922774c64736a6
BLAKE2b-256 checksum
How to use checksums
0e889c0c6f596d405710547b697ed8f78c8d62bf163a9289710da47c81f3dfee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / headless_reaper-0.1.5-py3-none-macosx_10_12_x86_64.whl

Download URL headless_reaper-0.1.5-py3-none-macosx_10_12_x86_64.whl
Size 368.0 kB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
9f2a866beaecbb38463e72c126d8db2022645c6535d7929cf68c5e707012e1c8
BLAKE2b-256 checksum
How to use checksums
8a11c58ef314edd2b2dfdca863746592b765950b376e7ecbaa57bd39d158f97e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Security for headless-reaper 0.1.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page