[opensourcedex]

npkill is a free, open source frameworks & platforms project written in TypeScript and released under MIT. It has 9,463 GitHub stars, 257 forks and 24 open issues, and was last pushed 30 days ago. On this registry it ranks #44 of 109 tracked projects in Frameworks & Platforms, with 5 head-to-head comparisons available.

What is npkill?

npkill is a command-line utility for JavaScript and TypeScript developers who want to find every node_modules directory on their machine, see how much disk space each one occupies, and delete the ones they no longer need.

What it is

npkill is an open-source terminal tool written in TypeScript and released under the MIT licence. It lives in the Node.js and npm ecosystem, where it complements the package manager rather than replacing it: npm installs dependencies, while npkill cleans up the directory trees those installs leave behind. Its own documentation describes it as a way to list any node_modules directory on your system along with the space it takes up, and then select which ones to erase in order to free disk space.

The concrete problem it addresses is workspace clutter. Developers who move between many projects accumulate node_modules folders that are large, frequently regenerated, and easy to forget about. The README frames the target as old and dusty node_modules cluttering up a machine, and the tool is built around making the removal of those folders as simple as reading a list and pressing a key rather than assembling long shell commands.

Key capabilities

  • Scans for node_modules directories starting at the path where the npkill command is executed, listing each one and the space it takes up.
  • Shows a last_mod column indicating when a file in the workspace was last modified, so recently touched projects are distinguishable from abandoned ones.
  • Supports interactive keyboard controls: ↓ ↑, j and k to move through results, Space or Del to delete the selected folder, o to open the directory holding the result, and Q or Ctrl + c to exit.
  • Provides search mode, entered with /, that filters results by a regex pattern — for example /work/.*/data to limit the list to paths under work that contain data.
  • Offers multi-select mode toggled with T, with Space to toggle a folder, V for range selection across consecutive entries, A to select or unselect all, and Enter to delete everything selected.
  • Highlights directories belonging to applications installed on the system that need their node_modules to work, marking them with a warning symbol so they are not removed by mistake.
  • Produces JSON output and exposes an API, and the README documents internationalized versions in Spanish, Indonesian, Portuguese and Turkish.

Who uses it and how

  • Developers with many local projects who run the scan from a chosen directory, review the listed folders and their sizes, and delete stale ones to reclaim disk space.
  • Users cleaning up a large backlog of directories, who enter multi-select mode and use range selection plus select-all before deleting everything in one operation.
  • People working with a specific subtree of their filesystem, who use search mode with a regex to narrow the result set before acting on it.
  • Users of non-English documentation, who follow the translated READMEs in Spanish, Indonesian, Portuguese or Turkish.
  • Contributors and learners reading the source, since the project is TypeScript, has few dependencies, and lists Hacktoberfest among its topics.

Getting started

No installation is required: run npx npkill directly, or install it globally with npm i -g npkill and invoke npkill (Unix users may need sudo).

How it compares

The available facts name no comparable cleanup or disk-space tool, so npkill stands alone in this registry; its relationship to npm and npx is complementary, since it removes dependency directories rather than managing packages.

When to use it — and when not

It suits a self-hoster or developer who simply runs a CLI, since there is no database, storage layer or SMTP service to operate, but the user must take responsibility for what is deleted: applications installed on the system may need their node_modules to function, and removing them can break those applications. It is not a package manager, does not manage dependency versions, and should not be used to touch directories you cannot regenerate with an install; 24 issues remain open against the project.

project readme (upstream, from github) — read inline

npm NPM

Easily find and remove old and heavy node_modules folders :sparkles:

This tool allows you to list any node_modules directories in your system, as well as the space they take up. You can then select which ones you want to erase to free up space. Yay!

i18n

We're making an effort to internationalize the Npkill docs. Here's a list of the available translations:

Table of Contents

:heavy_check_mark: Features

  • Clear space: Get rid of old and dusty node_modules cluttering up your machine.

  • Last Workspace Usage: Check when was the last time you modified a file in the workspace (indicated in the last_mod column).

  • Very fast: NPKILL is written in TypeScript, but searches are performed at a low level, improving performance greatly.

  • Easy to use: Say goodbye to lengthy commands. Using npkill is as simple as reading a list of your node_modules, and pressing Del to get rid of them. Could it be any easier? ;)

  • Minified: It barely has any dependencies.

:cloud: Installation

You don't really need to install it to use it! Simply use the following command:

$ npx npkill

Or if for some reason you really want to install it:

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

NPKILL does not support node

:clipboard: Usage

$ npx npkill
# or just npkill if installed globally

By default, npkill will scan for node_modules starting at the path where npkill command is executed.

Move between the listed folders with ↓ ↑, and use Space or Del to delete the selected folder. You can also use j and k to move between the results.

You can open the directory where the selected result is placed by pressing o.

To exit, Q or Ctrl + c if you're brave.

Important! Some applications installed on the system need their node_modules directory to work and deleting them may break them. NPKILL will highlight them by displaying a :warning: to be careful.

Search Mode

Search mode allows you to filter results. This can be particularly useful for limiting the view to a specific route or ensuring that only those results that meet the specified condition are “selected all.”

For example, you can use this expression to limit the results to those that are in the work directory and that include data somewhere in the path: /work/.*/data.

Press / to enter search mode. You can type a regex pattern to filter results.

Press Enter to confirm the search and navigate the filtered results, or Esc to clear and exit.

To exit from this mode, leave empty.

Multi-Select Mode

This mode allows you to select and delete multiple folders at once, making it more efficient when cleaning up many directories.

Entering Multi-Select Mode

Press T to toggle multi-select mode. When active, you'll see a selection counter and additional instructions at the top of the results.

Controls

  • Space: Toggle selection of the current folder.
  • V: Start/end range selection mode.
  • A: Toggle select/unselect all folders.
  • Enter: Delete all selected folders.
  • T: Unselect all and back to normal mode.

Range Selection

After pressing V to enter range selection mode:

  • Move the cursor with arrow keys, j/k, Home/End, or page up/down
  • All folders between the starting position and current cursor position will be selected/deselected
  • Press V again to exit range selection mode

Options

ARGUMENT DESCRIPTION
-p, --profiles Allows you to select the profile (set of targets) to use. If no option is specified, the available ones will be listed (node by default).
--config Path to a custom .npkillrc configuration file. By default, npkill looks first for ./.npkillrc and then for ~/.npkillrc.
-d, --directory Set the directory from which to begin searching. By default, starting-point is .
-D, --delete-all Automatically delete all folders that are found. Suggested to be used together with -x.
-e, --hide-errors Hide errors if any
-E, --exclude Exclude directories from search (directory list must be inside double quotes "", each directory separated by ',' ) Example: "ignore1, ignore2"
-f, --full Start searching from the home of the user (example: "/home/user" in linux)
--size-unit Set the unit for displaying folder sizes. (Available: auto, mb, gb). With auto, sizes

Examples

  • Search node_modules directories in your projects directory:
npkill -d ~/projects

# other alternative:
cd ~/projects
npkill
  • List node_modules in your projects directory, excluding the ones in progress and ignore-this directories:
npkill -d 'projects' --exclude "progress, ignore-this"
  • Automatically delete all node_modules that have sneaked into your backups:
npkill -d ~/backups/ --delete-all
  • Get results in JSON format for automation or further processing:
npkill --json > results.json
  • Stream results in real-time as JSON (useful for monitoring or piping to other tools):
npkill --json-stream | jq '.'
  • Save only successful results to a file, ignoring errors:
npkill --json-stream 2>/dev/null | jq -s '.' > clean-results.json

JSON Output

Npkill supports JSON output formats for automation and integration with other tools:

  • --json: Output all results as a single JSON object at the end of the scan
  • --json-stream: Output each result as a separate JSON object in real-time

For detailed documentation, examples, and TypeScript interfaces, see JSON Output Documentation.

Quick Examples:

# Get all results as JSON
npkill --json > results.json

# Process results in real-time
npkill --json-stream | jq '.result.path'

# Find directories larger than 100MB
npkill --json | jq '.results[] | select(.size > 104857600)'

:pager: Set Up Locally

# -- First, clone the repository
git clone https://github.com/voidcosmos/npkill.git

# -- Navigate to the dir
cd npkill

# -- Install dependencies
npm install

# -- And run!
npm run start


# -- If you want to run it with some parameter, you will have to add "--" as in the following example:
npm run start -- -f -e

:bookmark_tabs: API

The api allows you to interact with npkill from node to create your own implementations in your scripts (automations, for example).

You can check the basic API here or on the web (comming soon).

:crystal_ball: Roadmap

  • Release 0.1.0 !
  • Improve code
    • Improve performance
    • Improve performance even more!
  • Sort results by size and path
  • Allow the search for other types of directories (targets)
  • Reduce dependencies to be a more minimalist module
  • Allow to filter by directories that have not been used in a period of time
  • Create option for displaying directories in tree format
  • Add some menus
  • Add log service
  • Periodic and automatic cleaning (?)

:bug: Known bugs :bug:

  • Sometimes, CLI is blocked while folder is deleting.
  • Sorting, especially by routes, can slow down the terminal when there are many results at the same time.
  • Sometimes, size calculations are higher than they should be.
  • (SOLVED) Performance issues when searching from high level directories (like / in linux).
  • (SOLVED) Sometimes text collapses when updating the cli.
  • (SOLVED) Analyzing the size of the directories takes longer than it should.

If you find any bugs, don't hesitate and open an issue :)

:revolving_hearts: Contributing

If you want to contribute check the CONTRIBUTING.md

:coffee: Buy us a coffee

We have developed npkill in our free time, because we are passionate about the programming sector. Tomorrow we would like to dedicate ourselves to this, but first, we have a long way to go.

We will continue to do things anyway, but donations are one of the many ways to support what we do.

Open Collective donate button

Thanks!!

A huge thank you to our backers :heart:

Crypto alternative

  • btc: 1ML2DihUoFTqhoQnrWy4WLxKbVYkUXpMAX
  • bch: 1HVpaicQL5jWKkbChgPf6cvkH8nyktVnVk
  • eth: 0x7668e86c8bdb52034606db5aa0d2d4d73a0d4259

:scroll: License

MIT © Nya García Gallardo and Juan Torres Gómez

:cat::baby_chick:

Frequently asked questions

Is npkill free to use?

npkill is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does npkill do?

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 🧹

What is npkill written in?

npkill is primarily written in TypeScript. Its source is publicly available at https://github.com/voidcosmos/npkill, and it has 9,463 GitHub stars.