npkill Documentation

File: README.md Copy Chapter

Easily find and **remove** old and heavy **node_modules** folders :sparkles: Copy Section

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 Copy Chapter

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

• Español
• Indonesian
• Português
• Turkish

Table of Contents Copy Chapter

• Features
• Installation
• Usage
  • Multi-Select Mode
  • Options
  • Examples
  • JSON Output
• Set Up Locally
• API
• Roadmap
• Known bugs
• Contributing
• Buy us a coffee
• License

: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 npkill
# Unix users may need to run the command with sudo. Go carefully

NPKILL does not support node<v14. If this affects you you can use [email protected]

: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 Copy Chapter

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 Copy Chapter

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 Copy Section

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 Copy Section

• 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 Copy Section

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 Copy Chapter

Examples Copy Chapter

• 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 Copy Chapter

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.

Thanks!! Copy Section

A huge thank you to our backers :heart: Copy Chapter

Crypto alternative Copy Section

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

:scroll: License

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

:cat::baby_chick:

File: docs/RELEASE.md Copy Chapter

How to release a new version

1. Ensure the latest changes are available Copy Section

git checkout develop
git pull
git checkout main
git pull

2. Merge develop into main Copy Section

git merge develop --no-ff

3. Run the release script... Copy Section

# Ensure that the dependencies match those in package.json
rm -rf node_modules; npm i
npm run release

The release script takes care of 2 things:

• Execute the compilation tasks (npm run build).

• Start the interactive release process itself.

4. Pick version type (major, minor, path) Copy Section

5. Test the new release. Copy Section

File: README.es.md Copy Chapter

Encuentra y **destruye** directorios **node_modules** viejos y pesados :sparkles: Copy Section

Esta herramienta te permite listar cualquier directorio node_modules que haya en tu sistema, además del espacio que ocupa. Entonces puedes seleccionar los que quieras borrar para liberar espacio. ¡Yay!

i18n Copy Chapter

Nos estamos esforzando por internacionalizar la documentación de Npkill. Aquí tienes una lista de las traducciones disponibles:

• Español
• Português

Table of Contents Copy Chapter

• Características
• Instalación
• Uso
  • Opciones
  • Ejemplos
• Configuración local
• Roadmap
• Bugs conocidos
• Cómo contribuir
• Invítanos a un café
• Licencia

:heavy_check_mark: Características

• Libera espacio: Elimina tus directorios node_modules viejos y polvorientos que le roban espacio a tu máquina.

• Último uso del Workspace: Comprueba cuándo ha sido la última vez que has modificado un fichero en el workspace (indicado en la columna last_mod).

• Rapidez: NPKILL está escrito en TypeScript, pero las búsquedas se llevan a cabo a bajo nivel, lo que supone una mejora considerable del rendimiento.

• Fácil de utilizar: Despídete de comandos largos y difíciles. Utilizar Npkill es tan sencillo como leer la lista de tus node_modules, y pulsar la tecla Del para eliminarlos. ¿Podría ser más fácil? ;)

• Minificado: Apenas tiene dependencias.

:cloud: Instalación

¡Lo mejor es que no tienes que instalar Npkill para utilizarlo!
Simplemente utiliza el siguiente comando:

$ npx npkill

O, si por alguna razón te apetece instalarlo:

$ npm i npkill
# Los usuarios de Unix quizá tengan que ejecutar el comando con sudo. Ve con cuidado

NPKILL no tiene soporte para node<v14. Si esto te afecta puedes utilizar [email protected]

:clipboard: Uso

$ npx npkill
# o solo npkill si está instalado de forma global

Por defecto, Npkill comenzará la búsqueda de node_modules comenzando en la ruta donde se ejecute el comando npkill.

Muévete por los distintos directorios listados con ↓ ↑, y utiliza Space para borrar el directorio seleccionado.

También puedes usar j y k para moverte por los resultados.

Puedes abrir el directorio donde se aloja el resultado seleccionado pulsando o.

Para salir de Npkill, utiliza Q, o si te sientes valiente, Ctrl + c.

¡Importante! Algunas aplicaciones que están instaladas en el sistema necesitan su directorio node_modules para funcionar, y borrarlo puede romperlas. NPKILL te mostrará un :warning: para que sepas que tienes que tener cuidado.

Opciones Copy Chapter

Precaución: Algunos comandos pueden cambiar en versiones futuras

Ejemplo Copy Chapter

• Busca y encuentra los directorios node_modules en un directorio projects :

npkill -d ~/projects

# otra alternativa:
cd ~/projects
npkill

• Lista los directorios llamados "dist" y muestra los errores que ocurran:

npkill --target dist -e

• Muestra el cursor de color magenta... ¡Porque me gusta el magenta!

npkill --bg-color magenta

• Lista los directorios vendor en un directorio projects, ordenados por tamaño y mostrando el tamaño en gb:

npkill -d '~/more projects' -gb --sort size --target vendor

• Lista los node_modules en el directorio projects, excluyendo los que están en los directorios progress e ignore-this:

npkill -d 'projects' --exclude "progress, ignore-this"

• Borra automáticamente todos los node_modules que se encuentren en el directorio backups:

npkill -d ~/backups/ --delete-all

:pager: Configuración local

# -- Primero, clona el repositorio
git clone https://github.com/voidcosmos/npkill.git

# -- Navega al dir
cd npkill

# -- Instala las dependencias
npm install

# -- ¡Y ejecuta!
npm run start


# -- Si quieres ejecutar con algún parámetro, hay que añadir "--", tal y como se muestra a continuación:
npm run start -- -f -e

:crystal_ball: Roadmap

• Lanzar la versión 0.1.0 !
• Mejorar el código
  • Mejorar el rendimiento
  • ¡Mejorar el rendimiento aún más!
• Ordenar los resultados por tamaño y ruta
• Permitir la búsqueda de otro tipo de directorios (targets)
• Reducir las dependencies para ser un módulo más minimalista
• Permitir el filtrado por directorios que no se hayan utilizado en un periodo de tiempo determinado
• Crear una opción para mostrar los directorios en formato árbol
• Añadir menús
• Añadir un servicio de logs
• Limpieza periódica y automática (?)

:bug: Bugs conocidos :bug:

• A veces, el CLI se bloquea mientras un directorio se está borrando.
• La ordenación, especialmente por rutas, puede ralentizar la terminal cuando haya muchos resultados al mismo tiempo.
• A veces, los cálculos de tamaño son mayores de lo que deberían ser.
• (RESUELTO) Problemas de rendimiento al hacer la búsqueda desde directorios de alto nivel (como / en Linux).
• (RESUELTO) A veces el texto se colapsa al actualizar el CLI.
• (RESUELTO) Analizar el tamaño de los directorios tarda más de lo que debería.

Si encuentras algún bug, no dudes en abrir un issue :)

:revolving_hearts: Cómo contribuir

Si quieres contribuir, échale un vistazo al CONTRIBUTING.md

:coffee: Invítanos a un café

Hemos desarrollado Npkill en nuestro tiempo libre, porque nos apasiona la programación.

El día de mañana nos gustaría dedicarnos al open source completamente, pero antes, nos queda un largo camino por recorrer.

Seguiremos contribuyendo al open source por y para siempre, pero las donaciones son una de las muchas formas de apoyarnos.

¡Invítanos a un café! (O a un té para Nya, la única programadora a la que no le gusta el café).

¡¡Mil gracias!! Copy Section

Muchísimas gracias a todos los que nos han apoyado :heart: Copy Chapter

Alternativa cripto Copy Section

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

:scroll: Licencia

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

:cat::baby_chick:

File: README.pt.md Copy Chapter

Encontre e **remova** facilemente pastas **node_modules** antigas e pesadas :sparkles: Copy Section

Esta ferramenta permite que você liste as pastas node_modules em seu sistema, bem como o espaço que ocupam. Então você pode selecionar quais deles deseja apagar para liberar espaço. ¡Yay!

i18n Copy Chapter

Estamos fazendo esforço para internacionalizar a documentação do Npkill. Aqui está uma lista das traduções disponíveis:

• Español
• Português

Table of Contents Copy Chapter

• Funcionalidades
• Instalação
• Utilização
  • Opções
  • Exemplos
• Configurar localmente
• Roteiro
• Problemas conhecidos
• Contribuindo
• Compre-nos um café
• Licença

:heavy_check_mark: Funcionalidades

• Liberar espaço: Livre-se dos antigos e empoeirados node_modules que ocupam espaço em sua máquina.

• Último Uso do Espaço de Trabalho: Verifique quando foi a última vez que você modificou um arquivo no espaço de trabalho (indicado na coluna última_modificação).

• Muito rápido: O NPKILL é escrito em TypeScript, mas as pesquisas são realizadas em um nível baixo, melhorando muito o desempenho.

• Fácil de usar: Diga adeus aos comandos longos. Usar o npkill é tão simples quanto ler uma lista de seus node_modules e pressionar Delete para se livrar deles. Pode ser mais fácil do que isso? ;)

• Minificado: Ele mal possui dependências.

:cloud: Instalação

Você nem precisa instalá-lo para usar!
Basta usar o seguinte comando:

$ npx npkill

Ou, se por algum motivo você realmente deseja instalá-lo:

$ npm i npkill
# Usuários do Unix podem precisar executar o comando com sudo. Tome cuidado.

O NPKILL não suporta versões node<v14. Se isso afeta você, use [email protected].

:clipboard: Utilização

$ npx npkill
# ou apenas npkill se você instalou globalmente

Por padrão, o npkill fará a varredura em busca de node_modules a partir do local onde o comando npkill é executado.

Para mover entre as pastas listadas, utilize as teclas ↓ e ↑, e use Space ou Del para excluir a pasta selecionada.
Você também pode usar j e k para se mover entre os resultados.

Para abrir o diretório onde o resultado selecionado está localizado, pressione o.

Para sair, use Q ou Ctrl + c se você estiver se sentindo corajoso.

Importante! Algumas aplicações instaladas no sistema precisam do diretório node_modules delas para funcionar, e excluí-los pode quebrá-las. O NPKILL irá destacá-los exibindo um :warning: para que você tenha cuidado.

Opções Copy Chapter

Aviso: No futuro alguns comandos podem mudar

Examples Copy Chapter

• Busque pastas node_modules no seu diretório de projetos:

npkill -d ~/projetos

# alternativa:
cd ~/projetos
npkill

• Listar diretórios com o nome "dist" e mostrar erros, se houver algum:

npkill --target dist -e

• Exibe o cursor na cor magenta... porque eu gosto de magenta!

npkill --bg-color magenta

• Listar pastas vendor no seu diretório de projetos, ordenar por tamanho e mostrar o tamanho em GB:

npkill -d '~/more projetos' -gb --sort size --target vendor

• Listar node_modules no seu diretório de projetos, exceto nas pastas progresso e ignorar:

npkill -d 'projetos' --exclude "progresso, ignorar"

• Exclua automaticamente todos os node_modules que tenham entrado em seus backups:

npkill -d ~/backups/ --delete-all

:pager: Configurar localmente

# -- Primeiramente, clone o repositório
git clone https://github.com/voidcosmos/npkill.git

# -- Acesse a pasta
cd npkill

# -- Instale as dependências
npm install

# -- E rode!
npm run start


# -- Se você deseja executá-lo com algum parâmetro, você terá que adicionar "--" como no seguinte exemplo:
npm run start -- -f -e

:crystal_ball: Roteiro

• Lançamento 0.1.0 !
• Melhorias de código
  • Melhorias de performance
  • Ainda mais melhorias de performance!
• Ordenação de resultados por tamanho e localização
• Permitir a pesquisa por outros tipos de diretórios (alvo)
• Reduzir as dependências para tornar o módulo mais minimalista
• Permitir filtrar por diretórios que não foram usados em um período de tempo
• Criar opção para mostrar as pastas em formato de árvore
• Adicionar menus
• Adicionar logs
• Limpeza automatizada periódica (?)

:bug: Problemas conhecidos :bug:

• Às vezes, a CLI fica bloqueada enquanto a pasta está sendo excluída.
• Alguns terminais que não utilizam TTY (como o git bash no Windows) não funcionam.
• A ordenação, especialmente por rotas, pode deixar o terminal mais lento quando há muitos resultados ao mesmo tempo.
• Às vezes, os cálculos de tamanho são maiores do que deveriam ser.
• (RESOLVIDO) Problemas de desempenho ao pesquisar em diretórios de alto nível (como / no Linux).
• (RESOLVIDO) Às vezes, o texto se desfaz ao atualizar a interface de linha de comando (CLI).
• (RESOLVIDO) A análise do tamanho dos diretórios leva mais tempo do que deveria.

Se você encontrar algum erro, não hesite em abrir uma solicitação (via issue) :)

:revolving_hearts: Contribuindo

Se você quer contribuir confira o CONTRIBUTING.md

:coffee: Compre-nos um café

Desenvolvemos o npkill em nosso tempo livre, porque somos apaixonados pelo setor de programação. Amanhã, gostaríamos de nos dedicar mais a isso, mas antes, temos um longo caminho a percorrer.

Continuaremos a fazer as coisas de qualquer maneira, mas as doações são uma das muitas formas de apoiar o que fazemos.

Obrigado!! Copy Section

Um enorme agradecimento aos nossos apoiadores :heart: Copy Chapter

via Crypto Copy Section

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

:scroll: Licença

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

:cat::baby_chick: