npkill: An Interactive Tool for Finding and Removing node_modules Folders

The node_modules Accumulation Problem

Every Node.js project pulls its dependencies into a local node_modules directory. After months of work across multiple repositories, those directories accumulate on a developer's machine: old projects, abandoned experiments, cloned repos from tutorials, and staging branches each carry their own copy of packages like React or TypeScript. The total disk use can grow to tens of gigabytes without any single directory being large enough to notice on its own.

npkill is a TypeScript CLI that addresses this by scanning your file system for all node_modules directories, displaying how much space each one occupies, and providing a keyboard-driven interface for selecting which ones to delete. It was created by Nya Garcia and Juan Torres and published under the MIT license.

The tool is aimed at individual developers who want to reclaim disk space on their development machines. It is not a project-level dependency manager or a replacement for npm's own dependency tools. Its scope is specifically the files on your disk, not the declared dependencies in a package.json.

How npkill Scans and Displays Results

npkill searches for node_modules directories starting from the path where you run the command, by default the current working directory. The search runs at a low level for performance, which the README notes contributes to its speed compared to a naive recursive file walk.

Results appear in a scrollable list with two columns: the directory path and the size it occupies on disk. A last_mod column shows when a file in the parent workspace was last modified, which helps identify old projects worth cleaning first. The size display uses auto mode by default: directories smaller than 1024 MB show in MB (rounded) and larger directories show in GB with decimals. The --size-unit flag lets you override this to mb or gb.

When npkill detects a node_modules directory that appears to belong to a system-level application, it marks the entry with a warning indicator. Deleting a system application's node_modules can break that application; the README calls out this risk explicitly.

Running npkill for the First Time

npkill requires Node 14 or newer (the package.json specifies 20.19.0 as the engine floor for the current release). No installation is needed to try it:

$ npx npkill

To install it globally for repeated use:

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

Once running, navigate the list with the up and down arrow keys, or with j and k. Press Space or Del to delete the selected folder. Press o to open the directory in the file manager. Press Q or Ctrl+C to exit without deleting anything.

To start scanning from a specific directory rather than the current one, pass -d:

$ npx npkill
# or just npkill if installed globally

The -f flag starts the search from the user's home directory, which is the widest possible scan. The -D flag deletes every found directory automatically without prompting, which the README recommends combining with -x for safety.

Search Mode and Multi-Select for Batch Cleanup

When a developer has many projects to clean, selecting them one at a time is slow. npkill provides two mechanisms for working with multiple directories at once.

Search mode lets you filter the displayed results by a regex pattern. Press / to enter search mode, type a pattern, and press Enter to apply the filter. The filtered view limits both what you see and what a select-all operation covers. Exiting search mode by leaving the pattern empty restores the full list.

Multi-select mode, toggled with T, allows marking multiple directories for deletion in one batch. Once in multi-select mode, Space toggles the selection on the current entry. Pressing V starts range selection: moving the cursor selects or deselects everything between the starting position and the current cursor position. Pressing A toggles all visible entries. Pressing Enter deletes all currently selected entries. Pressing T again unselects everything and exits multi-select mode.

These two modes work together: filter the results to a specific workspace or pattern first, then select-all and delete in one step. This is the practical path for cleaning up a directory tree with many old Node.js projects.

Limitations and Safety Considerations

npkill deletes directories immediately. It does not move them to the trash first or prompt for confirmation on each deletion. The warning indicator for system-owned directories is the only safety mechanism the tool provides before a delete happens. Once deleted, a node_modules directory can only be restored by running npm install again in that project.

npkill covers only node_modules. It does not clean Python virtual environments (.venv), Gradle caches (.gradle), Maven local repositories (.m2), or Cargo build artifacts. Developers who need to clean multiple types of build caches across different language ecosystems will need separate tools for each.

The package.json sets Node >= 20.19.0 as the engine floor for the current version. The README notes that Node versions below 14 are not supported and directs those users to [email protected] instead.

The tool also does not evaluate whether a node_modules directory is still needed by an active project. It shows when the workspace was last modified (the last_mod column), but the decision of whether a project is abandoned is left entirely to the user.

Comparing npkill to Manual Cleanup Commands

The shell alternative to npkill is a find command that locates and removes all node_modules directories recursively. This works and requires nothing installed, but it operates blindly: it removes all matching directories without showing their sizes, without letting you exclude specific ones, and without any warning about system-owned paths. On a machine with many projects, a single find command can delete a directory you wanted to keep.

npkill's interactive TUI makes the difference. You see the size of each directory before you delete it, you can filter by path to exclude directories from an active project, and the warning indicator flags system-level paths. The total space recovered is visible incrementally as you delete entries.

npm prune is a different tool with a different goal: it removes packages from an existing node_modules that are no longer listed in package.json, leaving the project's current dependencies intact. It is for trimming an existing installation, not for cleaning up abandoned installations across a file system. The two tools are complementary rather than alternatives.

Maintenance, License, and Version Notes

The last push to the repository was on 2026-09-08. The current released version is 0.12.2, published on 2024-06-08. The repository is licensed under the MIT license, which permits use in any context with no restrictions beyond attribution.

The project has a small set of runtime dependencies: ansi-escapes for terminal control, open-file-explorer for the o key's file manager integration, and picocolors for output coloring. The minimal dependency footprint reduces the surface area for supply chain concerns, which is a meaningful consideration for a tool that runs with the permissions needed to delete directories.

The authors distribute npkill as a single global CLI with no configuration file required for basic use. A .npkillrc configuration file is supported for users who want to persist settings: the --config flag points npkill at a custom configuration file path, and it also checks for ./.npkillrc and then ~/.npkillrc by default.

Editorial conclusion

npkill is the right tool when you want to reclaim disk space from old Node.js projects scattered across your machine and you want to see exactly what you are deleting before you delete it. The interactive TUI gives you control that a single find command does not. The limitation is that npkill only handles node_modules; it does not clean other build caches, .gradle directories, or virtual environments. For a quick one-time cleanup, npx npkill needs nothing installed. For regular use on a large tree of projects, the global install and the --directory flag let you target a specific workspace root.

Frequently asked questions

Official sources

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