No te compliques la vida trabajando con Node: nvm al rescate

¿Te ha pasado que clonas un proyecto en Node, corres el primer npm install… y lo único que recibes a cambio es una tormenta de errores y mensajes crípticos sobre incompatibilidades de versión? A mí sí... y muchas veces.

Esto por lo general ocurre por no usar la versión exacta con la que se desarrolló el proyecto. Horas perdidas intentando “arreglar” algo que en realidad no estaba roto, solo estaba ejecutándose en el ecosistema equivocado.

Por suerte, conocí nvm (Node Version Manager), una herramienta que me salvó de más de una batalla y que hoy considero un must-have para cualquier persona que desarrolle en Node.

Capítulo 1: Instalación

La instalación de nvm es sencilla, y la documentación oficial ya cubre el paso a paso en detalle. Aquí te dejo el enlace para que, si quieres, revises las instrucciones completas:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions - nvm-sh/nvm

GitHubnvm-sh

1.1 Linux

Es tan simple como ingresar el siguiente comando en tu terminal.

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

1.2 MacOs

Aquí existen dos formas: La primera es ingresar en la terminal el mismo comando de linux, o la segunda (y mi preferida) es utilizar el famoso gestor de paquetes brew. Simplemente debes ingresar a tu terminal y escribir este comando.

$ brew install nvm

Si quieres más información sobre brew te adjunto la documentación oficial de este gestor de paquetes para Mac.

Homebrew

The Missing Package Manager for macOS (or Linux).

Homebrew

1.3 Windows

No existe una versión oficial de nvm para Windows, pero sí un port muy popular desarrollado por la comunidad.

Releases · coreybutler/nvm-windows

A node.js version management utility for Windows. Ironically written in Go. - coreybutler/nvm-windows

GitHubcoreybutler

Buscar el nvm-setup.exe y sigue los pasos del instalador.

Capítulo 2: Comandos útiles

Ahora sí, vamos a lo importante. La lista completa de comandos de nvm puede resultar algo confusa, sobre todo si no sueles trabajar con la terminal.

Por eso aquí te comparto los que más utilizo en mi día a día, con explicaciones claras y ejemplos prácticos para que puedas aplicarlos al instante.

Antes de comenzar, probemos si tienes nvm instalado y en qué versión:

$ nvm -v

2.1 Instalación de versiones

nvm no solo te permite instalar versiones de Node.js, sino también elegir exactamente cuál usar.

2.1.1 Instalar el último patch de una versión: Si quieres instalar, por ejemplo, la versión 20 con su último patch disponible:

$ nvm install 20

En este caso, si la versión más actual de la rama 20 es v20.19.4 (lanzada el 15 de julio de 2025), ese será el archivo que descargará e instalará. No tendrás que preocuparte de buscar manualmente el número exacto.

2.1.2 Instalar una versión específica: Si necesitas una versión exacta:

$ nvm install 20.9.0

2.1.3 Instalar por codename: Las versiones LTS siempre tienen un nombre clave que los identifica. Por ejemplo la versión 20 se llama iron.

$ nvm install lts/iron

Esto instalará la versión 20 con su último patch, igual como sucedió en 2.1.1

Puedes consultar los codenames aquí:

Node.js — Node.js Releases

Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.

2.1.4 Instalar la última versión LTS disponible: Perfecto para comenzar un proyecto sin preocuparte por versiones.

$ nvm install --lts

2.2 Uso de versiones

Instalar una versión no significa que la estés usando, pero nvm te permite alternar fácilmente.

2.2.1 Usar el último patch de una versión: Este comando buscará el último patch instalado de esa versión en específico.

$ nvm use 20

Supongamos lo siguiente:

• 20.19.4 → Existe, pero no instalada
• 20.18.3 → Instalada ✅
• 20.9.0 → Instalada ✅

En este caso, se ejecutará 20.18.3 porque es la más reciente que tienes, incluso si existe una más nueva en internet.

2.2.2 Usar una versión específica:

$ nvm use 20.9.0

2.2.3 Usar por codename: Funciona igual que 2.2.1

$ nvm use lts/iron

2.2.4 Usar la última LTS instalada:

$ nvm use --lts

2.3 Listar versiones

Para saber qué versiones existen y cuáles tenemos.

2.3.1 Ver versiones instaladas.

$ nvm ls

2.3.2 Versiones existentes: Ver todas las versiones disponibles para instalar.

$ nvm ls-remote

2.3.3 Versiones LTS: Ver solo las versiones LTS disponibles para instalar.

$ nvm ls-remote --lts

2.3.4 Eliminar versiones.

$ nvm uninstall 18

Esto aplica para versiones generales, versiones específicas y versiones con codename

2.4 Uso de alias

Los alias en nvm son como atajos: te permiten asignar un nombre fácil de recordar a una versión específica de Node.js.

2.4.1 Ver alias creados.

$ nvm alias

2.4.2 Crear un alias: Supongamos que estás trabajando en un proyecto llamado "proyecto-1" que necesita la versión 23.9.0. Puedes crear un alias con ese nombre:

$ nvm alias proyecto-1 23.9.0

Luego, cada vez que quieras cambiar a esa versión, no necesitas recordar el número exacto, basta con:

$ nvm use proyecto-1

2.4.3 Dejar una versión por defecto: También puedes elegir qué versión quieres que se cargue automáticamente cada vez que abras una terminal. Por ejemplo, si quieres que 24.6.0 sea tu versión predeterminada:

$ nvm alias default 24.6.0

De esta forma, no tendrás que escribir nvm use cada vez que abras una nueva sesión.

2.4.4 Eliminar un alias.

$ nvm unalias proyecto-1

Capítulo 3: Fijar la versión en Proyectos

Cuando en un proyecto te dicen el clásico “funciona en mi máquina” pero falla en la tuya, casi siempre hay un culpable silencioso: la versión de Node. Para evitar ese dolor, nvm permite dejar escrita la versión que debe usarse en cada proyecto con un simple archivo: .nvmrc.

3.1 ¿Qué es .nvmrc?

Es un archivo de una sola línea, ubicado en la raíz del proyecto, que indica qué versión de Node debe usarse allí.

Puede contener:

• Una versión exacta como: 20.9.0 o v20.9.0
• Una major (último patch de esa mayor): 20
• Una LTS concreta por codename: lts/iron

Existen más formatos, pero solo nos centraremos en esos tres.

3.2 Crear el archivo

La forma más simple es ir a la raíz del proyecto y crear un archivo de texto plano llamado .nvmrc. Dentro, solo necesitas escribir la versión de Node que quieras usar.

Así debería verse tu proyecto con el archivo .nvmrc agregado:

.
├── .gitignore
├── .nvmrc # El archivo en la raiz del proyecto
├── .prettierrc
├── eslint.config.mjs
├── nest-cli.json
├── node_modules
├── package-lock.json
├── package.json
├── README.md
├── src/
├── test/
├── tsconfig.build.json
└── tsconfig.json

Ahora, si lo quieres hacer como un pro, solo debes ir a la raiz de tu proyecto, pero en vez de crear el archivo manualmente, puedes escribir este comando en la terminal y se creará el archivo automáticamente junto con la versión deseada.

$ echo "lts/jod" > .nvmrc

3.3 Uso del día a día

Una vez creado el archivo, ya puedes usarlo en tu día a día dentro de la carpeta del proyecto

$ nvm install   # Lee el .nvmrc e instala la versión si falta
$ nvm use       # Cambia tu shell a esa versión

Capítulo 4: Extras

Antes de finalizar, me gustaría dejar uno puntos importantes que no se explicaron previamente y que te ahorrarán un dolor de cabeza:

4.1 Paquetes globales

Cada versión de Node instalada con nvm mantiene su propio set de paquetes globales.

Esto significa que si instalas TypeScript con:

$ npm i -g typescript

en la versión lts/iron, luego cambias a otra versión (lts/jod, por ejemplo) y ejecutas tsc, no funcionará, porque ese binario solo está disponible en la versión donde lo instalaste.

En otras palabras, cada versión de Node tiene su propia carpeta de node_modules globales, totalmente independiente de las demás.

4.2 Reinstalar paquetes globales

Ya vimos que cada versión de Node instalada con nvm mantiene su propio set de paquetes globales, y que al cambiar de versión puedes “perder” herramientas que usabas, como typescript o @nestjs/cli, entre otros.

Para no tener que reinstalar todo manualmente, nvm trae un comando muy práctico:

$ nvm reinstall-packages <version_base>

Este comando copia todos los paquetes globales instalados en una versión de Node hacia otra.

Supongamos que estabas trabajando en lts/iron y tenías instalado TypeScript de forma global:

$ nvm use lts/iron      # Utilizar la versión iron
$ npm i -g typescript   # Instalar el paquete typescript de forma global

Luego decides instalar y usar la versión lts/gallium. Como recordarás, en esta versión no están instalados los paquetes globales que tenías antes. Para evitar reinstalar uno por uno, basta con:

$ nvm install lts/gallium           # instalar la versión gallium
$ nvm use lts/gallium               # utilizar gallium
$ nvm reinstall-packages lts/iron   # instalar los paquetes globales de iron en gallium

Y listo, ahora lts/gallium tendrá los mismos paquetes globales que usabas en lts/iron.

Ten en cuenta que algunos paquetes globales pueden no ser totalmente compatibles con la nueva versión de Node, así que si algo falla, reinstálalo manualmente.

Capítulo 5: Despedida

En resumen, nvm es la herramienta que te evita dolores de cabeza con versiones en Node. Una vez que la integras en tu flujo, tu equipo trabajará en sincronía y hasta tu yo del futuro te lo agradecerá.