Hay un momento en la vida de toda máquina de desarrollo en el que uno se pregunta: ¿qué demonios instalé aquí y cuándo? Entre el npm install -g de aquel tutorial de hace dos años y la CLI que probaste una tarde y nunca volviste a abrir, el directorio global de npm se convierte en un desván.
Para ordenar ese desván bastan dos comandos. Uno te dice qué hay. El otro, qué se ha quedado viejo.
Primero: qué significa "global"
Cuando instalas un paquete con npm install a secas, va a la carpeta node_modules del proyecto en el que estás. Vive y muere con ese proyecto.
Cuando lo instalas con -g, va a un directorio del sistema y sus ejecutables quedan disponibles desde cualquier sitio de la terminal. Ahí es donde acaban las herramientas de línea de comandos: TypeScript, ESLint, nodemon, las CLI de despliegue, el propio npm.
Si quieres ver dónde está esa carpeta en tu equipo:
npm root -g
Los dos comandos de los que va esta entrada operan sobre ese directorio, no sobre el proyecto en el que estés parado.
npm ls -g --depth=0
Lista lo que tienes instalado globalmente, con su versión:
$ npm ls -g --depth=0
/usr/local/lib
├── eslint@8.57.0
├── npm@10.8.2
├── nodemon@3.1.0
└── typescript@5.4.5
La clave está en --depth=0. Sin él, npm despliega el árbol completo de dependencias: las dependencias de TypeScript, las dependencias de esas dependencias, y así hasta el infinito. Con --depth=0 le dices solo el primer nivel, es decir, solo lo que instalaste tú a conciencia. Que es justo lo que quieres saber.
Un detalle sobre versiones de npm
En npm 6 y anteriores, --depth=0 era imprescindible o la salida era una cascada ilegible. Desde npm 7, el comportamiento por defecto ya es mostrar solo el primer nivel, así que el flag se ha vuelto redundante. No molesta, y sigue siendo útil escribirlo por costumbre y por compatibilidad: funciona igual en cualquier versión.
Variantes que uso
# Solo los nombres, sin dibujo de árbol
npm ls -g --depth=0 --parseable
# En JSON, para procesarlo con un script
npm ls -g --depth=0 --json
# Guardar un respaldo antes de formatear la máquina
npm ls -g --depth=0 > paquetes-globales.txt
Ese último es oro puro cuando vas a reinstalar el sistema operativo.
npm outdated -g
Coge esa misma lista, la compara con lo que hay publicado en el registro de npm y te enseña solo lo que está desactualizado:
$ npm outdated -g
Package Current Wanted Latest Location
eslint 8.57.0 8.57.0 9.9.1 global
typescript 5.4.5 5.4.5 5.9.2 global
Si no imprime nada, enhorabuena: lo tienes todo al día. El silencio es buena noticia.
Las tres columnas de versión
Columna Qué significa
Current La versión que tienes instalada ahora mismo.
Wanted La versión más alta compatible con el rango semver declarado. Actualizar hasta aquí se considera seguro.
Latest La última publicada, aunque implique un salto de versión mayor con cambios incompatibles.
En el ejemplo de arriba, ESLint está en la 8.57.0 y la última es la 9.9.1: es un salto mayor, con cambios de configuración que pueden romperte cosas. TypeScript va de 5.4.5 a 5.9.2, mismo mayor, mucho menos arriesgado.
En paquetes globales verás que Current y Wanted suelen coincidir, porque no hay un package.json de proyecto imponiendo rangos.
Un truco para scripts
npm outdated devuelve código de salida 1 cuando encuentra algo desactualizado y 0 cuando todo está al día. Contraintuitivo si esperabas que "1" significara error, pero muy práctico: puedes engancharlo a un script que te avise cada lunes.
Y ahora, ¿cómo actualizo?
Los dos comandos anteriores solo miran, no tocan nada. Para actualizar tienes dos caminos:
# Camino prudente: actualiza hasta "Wanted", sin saltos mayores
npm update -g
# Camino decidido: salta a "Latest", asumiendo posibles roturas
npm install -g typescript@latest
Mi consejo después de algún susto: npm update -g a lo bruto está bien para paquetes menores, pero cuando la columna Latest muestra un salto de versión mayor, actualiza ese paquete a mano y de uno en uno. Y lee las notas de la versión antes.
Dos avisos de los que aprendí por las malas
Si usas nvm, cada versión de Node tiene sus propios paquetes globales. Cambias de Node 18 a Node 22 y de repente "desaparecen" todas tus herramientas. No han desaparecido: estás mirando otro directorio. Para llevártelas contigo existe nvm reinstall-packages <versión-anterior>.
Menos es más. Antes de actualizar la lista entera, mírala bien y pregúntate qué usas de verdad. Casi siempre hay dos o tres cosas que puedes desinstalar directamente con npm uninstall -g nombre-del-paquete. Hoy, además, muchas CLI se pueden ejecutar puntualmente con npx sin instalar nada.
Resumen
npm ls -g --depth=0 → qué tengo instalado globalmente.
npm outdated -g → qué se me ha quedado viejo.
npm update -g → ponerlo al día sin saltos mayores.
Tres minutos cada pocos meses y el desván deja de dar miedo.
