CLI tool
voidcosmos/npkill avatar
voidcosmos/npkill

npkill: the directory lister that deletes whole trees

Project brief: List any node_modules dir in your system and how heavy they are. You can then select which ones you want to erase to free up space.

9,523 stars264 forksTypeScriptMIT

At a glance

What is it?
npkill walks down from the directory you launch it in, lists every node_modules folder it finds with its size and a last_mod date, and deletes the rows you mark. It is quick and light on dependencies, but its safety signals are visual hints rather than guards, and the version advice in the README disagrees with the engines field in package.json on main.
Who is it for?
npkill suits a developer machine that has accumulated node_modules folders and wants an interactive list with sizes before anything is removed. Do not put -D in a script, and do not run it with -f/--full on a machine with globally installed tools until you have narrowed the scan root with -d/--directory or -E/--exclude.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 16, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • voidcosmos/npkill9,523 ★ · +111
Star history
Repository2026-08-042026-11-16
voidcosmos/npkill9.4k9.5k

111 Stars in the last 104 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The scan starts wherever you happen to launch the command

npkill builds its list by walking downward from the directory where the command runs, and with no arguments the starting point is the current one. Every profile target below that point shows up with the space it occupies. Two flags move the root: -d/--directory sets an explicit starting directory, and -f/--full starts the search from the home of the user, the README giving /home/user on linux as the shape of that path. Installation is meant to be frictionless, because the tool resolves through npx:

bash
$ npx npkill

The global route exists too, with a caveat attached to it in the same code block:

bash
$ npm i -g npkill
# Unix users may need to run the command with sudo. Go carefully

That sudo note is the first place permission enters the picture. A global install writes outside your home directory, and the search that follows can reach into paths a user account cannot read, which is why -e/--hide-errors exists. On startup npkill also checks for updates unless you pass -nu, --no-check-update, a network round trip you may want to switch off on an isolated machine.

Deleting a row removes the whole node_modules tree

Pressing Space or Del on a row deletes that node_modules directory outright. There is no prune step, no dependency resolution, and no trash stage between the keystroke and the removal. The README states that some applications installed on the system need their node_modules directory to work and that deleting them may break them, and it says npkill marks those rows with a warning. Treat that mark as a hint painted in the list, not a lock: nothing in the documented key bindings stops you from deleting a flagged row, and the only ways to keep such a directory alive are to keep it outside the scan root or to exclude it with -E/--exclude. That flag wants its list inside double quotes with each directory separated by a comma, exactly like the README example "ignore1, ignore2". No undo or recovery step is documented, so the repair after a mistake is reinstalling that project's dependencies yourself.

last_mod is a file timestamp and nothing more

The last_mod column reports when a file in that workspace was last modified, and it is the only recency signal in the display. It does not know whether the project is still active, whether the directory belongs to a globally installed tool, whether it sits inside a monorepo whose sibling packages still build from it, or whether you will need it tomorrow for a machine you have not touched yet. A folder abandoned two years ago and a folder you ran a build in this morning can look alike, and a freshly modified project can still be the largest entry in the list. Formatting makes comparisons harder rather than easier: --size-unit takes auto, mb or gb, where auto shows anything under 1024MB in MB rounded and anything larger in GB with decimals, so a 900MB tree and a 1.1GB one are rendered in different units even though both are simply large. If your decision depends on weight, pick mb or gb so the numbers sit on one scale, and remember that size never indicates whether deletion is safe.

-D takes the review step out of the loop

-D, --delete-all automatically deletes all folders that are found, and the option table suggests using it together with -x. Pair that with -f/--full and you have a sweep of everything under your home directory with no list in front of you, which also means the warning mark for system-installed applications has no row to sit in, because there is no row at all. Read -D as a wipe of the scan root rather than as cleanup. If you want something you can repeat, keep the interactive session and constrain it there instead: press / to enter search mode and type a regex such as /work/.*/data so only paths inside work with data in them remain, press Enter to confirm, then toggle multi-select mode with T, mark everything that survived the filter with A, and press Enter to delete that selection. The filter is what makes a bulk action defensible, so confirm it with Enter rather than clearing it with Esc before you start marking.

The Node floor in the README and the one in package.json disagree

The only version note in the README says npkill does not support node<v14 and directs older users to [email protected]. The package.json on main, still at version 0.12.2, declares engines node >=20.19.0, sets type to module, and points exports at ./lib/index.js. The two statements cover different worlds: the README implies Node 14 and newer are supported, while the manifest on main asks for 20.19.0 or newer. A developer on a modern LTS still has to check the engines field themselves to know whether their patch level qualifies. Engines fields are enforced by some package managers and ignored by others, so the failure mode can be a refused install rather than a clear message, which makes it worth verifying your own Node version before you recommend this tool to anyone else.

npx npkill hands you v0.12.2, not the current state of main

The newest release is v0.12.2 dated 2024-06-08, preceded by v0.12.1 on 2024-05-31 and v0.12.0 on 2024-05-30. The repository itself is not archived and its last push is 2026-10-31, so commits have landed on main long after that release. Since npx resolves against what is published, the version you actually run is the June 2024 build, and fixes sitting on main are not in it. If you need the current code, work from a checkout, where package.json wires the build to tsc and the test run to jest with experimental module flags:

bash
$ npm run build
$ node --experimental-vm-modules --experimental-modules node_modules/jest/bin/jest.js

Two metadata details matter when you trace the project. The package points its repository URL at github.com/zaldih/npkill while the repository under review is voidcosmos/npkill, so issue links and clone instructions may not land where you expect. And the -p flag links to a profile document at ./docs/profiles.md rather than spelling out the target sets inline, which means the authoritative list of what npkill searches for lives in a file you have to open.

Search mode and range selection both act on the visible list

Two bulk mechanisms widen the blast radius, and both are driven from the same filtered view. Search mode opens with / and takes a regex, with Enter to confirm and Esc to clear, and leaving it empty exits the mode. Multi-select mode toggles with T and adds four bindings: Space marks or unmarks the current row, A marks or unmarks every folder in view, V starts and ends a range, and Enter deletes all marked folders. Range mode anchors on the row you pressed V in and spans to the cursor, which you can drive with the arrow keys, j and k, Home, End, or page up and down, and pressing V again closes the span. Because A operates on what is currently visible, a regex left active silently decides what your sweep covers, and the o key opens the selected directory in the system file explorer, which is the sensible way to inspect a row before you commit. T unmarks everything and returns to normal mode.

Profiles define the targets and node is the only one named

The -p, --profiles flag selects a profile, described as a set of targets, and when no option is given the available ones are listed with node as the default. The definitions themselves sit in ./docs/profiles.md, and the options table links out rather than enumerating them. That gap decides what you can say about coverage: a question about whether npkill can clean up a python environment or any other ecosystem cannot be answered from the options table, because the profiles named there stop at node. The same applies to the machine-readable side. The table of contents links a JSON Output section and an API section, and API.md sits at the repository root, so read those sections, API.md and docs/profiles.md before you automate anything rather than inferring behaviour from the interactive display.

Editorial conclusion

npkill suits a developer machine that has accumulated node_modules folders and wants an interactive list with sizes before anything is removed. Do not put -D in a script, and do not run it with -f/--full on a machine with globally installed tools until you have narrowed the scan root with -d/--directory or -E/--exclude. Before rolling it out to a team, compare the node >=20.19.0 engines requirement against the Node version people actually run, and read docs/profiles.md if you need targets other than node.

Frequently asked questions

how to use npkill

Run npx npkill, move between listed folders with the arrow keys or j and k, press Space or Del to delete the selected folder, and press Q or Ctrl+c to exit. The search begins at the directory where the command is executed.

how to use npx npkill

npx npkill runs the tool without a global install. Because the scan starts at the path where you execute it, add -d/--directory to pick a different root or -f/--full to begin from your home directory.

what does npkill do

It lists node_modules directories with the space each one takes and the last_mod date of its workspace, then deletes the folders you select, one at a time with Space or Del, or in bulk from multi-select mode.

is npkill safe

The README warns that some applications installed on the system need their node_modules directory and that deleting them may break them, and npkill shows a warning on those rows. Deletion itself is not reversible from the interface and no undo is documented, so keep the scan root narrow.

What does npm prune do?

npm prune removes extraneous packages from a project's node_modules. npkill works one level up, at the directory: Space or Del removes the entire selected node_modules folder, and -D, --delete-all removes every folder it finds.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Community

Where developers are discussing it

Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 1 in the last 30 days; newest first.

Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/voidcosmos-npkill.svg)](https://hysenlabs.com/projects/voidcosmos-npkill)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/voidcosmos-npkill.svg)](https://hysenlabs.com/projects/voidcosmos-npkill)

Was this useful?