npkill

Once npkill is running, use the following keyboard shortcuts to manage node_modules folders:

• Navigate list: ↓ / ↑ or j / k
• Delete selected folder: Space or Del
• Open selected folder: o
• Quit: Q or Ctrl + C

Warning: npkill will mark certain folders with a :warning: icon if deleting them might break installed applications. Use caution.

To run npkill from the local repository:

1. Clone the repository.
2. Navigate to the directory.
3. Install dependencies.
4. Run the start script.

To pass arguments to the application when running via npm run start, use the -- separator.

git clone https://github.com/voidcosmos/npkill.git
cd npkill
npm install
npm run start

# To pass parameters:
npm run start -- -f -e

By default, npkill scans for node_modules starting from the directory where the command is executed.

Interactive Controls:

• Navigate: Use <kbd>↓</kbd> <kbd>↑</kbd> or <kbd>j</kbd> <kbd>k</kbd> to move between listed folders.
• Delete: Use <kbd>Space</kbd> or <kbd>Del</kbd> to remove the selected folder.
• Open Directory: Press <kbd>o</kbd> to open the directory of the selected result.
• Exit: Press <kbd>Q</kbd> or <kbd>Ctrl</kbd> + <kbd>c</kbd> to quit.

Warning: Some system applications require node_modules to function. npkill will mark these with a warning symbol (⚠️) to advise caution.

Npkill provides two JSON output modes for automation and integration:

1. Simple JSON (--json): Collects all scan results and outputs them as a single JSON object once the scan is complete. Best for batch processing.
2. Streaming JSON (--json-stream): Outputs each found directory as a separate JSON object on a new line immediately upon discovery. Best for real-time processing or handling very large scans.

Errors are emitted to stderr in a specific JSON format.

To run npkill from a local clone of the repository:

1. Clone the repository.
2. Enter the directory.
3. Install dependencies.
4. Run the start script.

To pass arguments to the underlying command when running via npm run start, use -- before the arguments.

Multi-select mode allows you to select and delete multiple folders at once.

How to use:

1. Press <kbd>T</kbd> to toggle multi-select mode.
2. Toggle selection: Use <kbd>Space</kbd> on the current folder.
3. Range selection: Press <kbd>V</kbd> to enter range selection mode. Use arrow keys, <kbd>j</kbd>/<kbd>k</kbd>, <kbd>Home</kbd>/<kbd>End</kbd>, or page up/down to select a range. Press <kbd>V</kbd>` again to exit range mode.
4. Select/Unselect all: Press <kbd>A</kbd>.
5. Delete all selected: Press <kbd>Enter</kbd>.
6. Exit/Unselect all: Press <kbd>T</kbd> to return to normal mode.

You can use npkill without installing it globally by using npx. If you prefer to have it installed on your system, you can install it via npm globally.

Note: Unix users may need to run the command with sudo.

Compatibility: npkill does not support Node.js versions < v14. If you are using an older version, use npkill@0.8.3.

You can customize npkill's behavior using a configuration file named .npkillrc. Npkill searches for this file in the following priority order:

1. A custom path provided via the --config flag.
2. The current working directory (./.npkillrc).
3. The user's home directory (~/.npkillrc).

The first file found will be used.

npkill --config /path/to/your/config.json

npkill uses "profiles" to define sets of directories that are generally safe to delete for specific ecosystems. By default, npkill uses the node profile. You can opt-in to other profiles using the --profiles flag with a comma-separated list of profile names.

Warning: While profiles target rebuildable caches and dependencies, always verify the results before deleting to ensure they are safe for your specific context.

Control how results are ordered and how their sizes are displayed.

sortBy options:

• "none": Order in which they are found (default)
• "size": Largest folders first
• "path": Alphabetical by path
• "age": Oldest modified projects first

sizeUnit options:

• "auto": < 1024MB in MB, larger in GB (default)
• "mb": Always in megabytes
• "gb": Always in gigabytes

{
  "sortBy": "size",
  "sizeUnit": "auto"
}

You can define custom profiles with specific targets (directory names) to search for. These can be activated using the -p or --profiles flag. Use defaultProfiles to specify which profiles are active by default.

Note: Custom profiles overwrite the base profiles.

{
  "defaultProfiles": ["node", "database"],
  "profiles": {
    "webdev": {
      "description": "Frontend web development artifacts and build outputs",
      "targets": ["dist", ".next", ".nuxt", ".output"]
    },
    "mystack": {
      "targets": ["venv", ".venv", "target", "__pycache__", ".gradle"]
    }
  }
}