Cómo instalar NVM para Node.js en Ubuntu: Guía técnica completa

NVM (Node Version Manager) es un script de shell compatible con POSIX que instala y gestiona múltiples entornos de ejecución Node.js aislados en una sola máquina, sin necesidad de privilegios de root ni modificar las rutas del sistema. Cada versión de Node.js reside en su propio directorio bajo `~/.nvm/versions/node/`, lo que proporciona un aislamiento completo y sin conflictos entre proyectos.

Esta guía describe una instalación de NVM de nivel de producción en Ubuntu (20.04, 22.04 y 24.04), cubriendo no solo los comandos básicos, sino también los casos especiales de archivos de perfil de shell, automatización del flujo de trabajo con `.nvmrc`, migración de paquetes globales y problemas específicos de servidores que la mayoría de los tutoriales omiten.

Por qué usar NVM en lugar del gestor de paquetes del sistema

Instalar Node.js mediante `apt` coloca un único binario a nivel de sistema en `/usr/bin/node`. Actualizarlo afecta a todas las aplicaciones del host simultáneamente. En una máquina de desarrollo compartida o un VPS que ejecuta múltiples proyectos Node.js, esto crea entornos frágiles y difíciles de reproducir.

NVM resuelve esto instalando cada versión de Node.js en un directorio de espacio de usuario y manipulando `PATH` a nivel de shell. El resultado es un control de versiones por usuario y por proyecto sin ningún impacto en el estado de paquetes del sistema operativo.

NVM vs. otros gestores de versiones de Node.js

NVM sigue siendo la opción más documentada y con mayor soporte del ecosistema, lo que la convierte en la opción predeterminada más segura para equipos y entornos de servidor donde la reproducibilidad importa más que la velocidad de inicio bruta.

Requisitos previos

• Ubuntu 20.04, 22.04 o 24.04 (escritorio o servidor)
• Una cuenta de usuario no root con privilegios `sudo`
• `curl` o `wget` instalado (ambos están presentes por defecto en la mayoría de las imágenes de Ubuntu)
• Familiaridad básica con Bash o Zsh

Para confirmar su shell y versión de Ubuntu antes de comenzar:

“`bash

echo $SHELL

lsb_release -a

“`

Paso 1: Actualizar el índice de paquetes del sistema

Actualice las listas de paquetes APT para asegurarse de que las dependencias resueltas durante la sesión estén al día:

“`bash

sudo apt-get update && sudo apt-get upgrade -y

“`

También confirme que `curl` está disponible:

“`bash

curl –version || sudo apt-get install -y curl

“`

Paso 2: Descargar y ejecutar el script de instalación de NVM

El instalador oficial de NVM está alojado en GitHub. Clona el repositorio de NVM en `~/.nvm` y añade el bloque de inicialización de shell necesario a su archivo de perfil.

Opción A — Usando curl (recomendado):

“`bash

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

“`

Opción B — Usando wget:

“`bash

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

“`

Verifique siempre la etiqueta de la última versión en la página de lanzamientos de NVM en GitHub antes de ejecutar. Reemplace `v0.40.1` con la etiqueta estable actual si se ha publicado una versión más reciente.

Lo que el instalador realmente hace:

1. Clona el repositorio de NVM en `~/.nvm`
2. Detecta su shell activo (`bash`, `zsh`, `ksh` o `fish`)
3. Añade el siguiente bloque de inicialización al archivo de perfil apropiado (`~/.bashrc`, `~/.zshrc`, `~/.profile` o `~/.bash_profile`)

“`bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"

“`

Nota de seguridad: Canalizar un script remoto directamente a `bash` es un patrón común pero conlleva un riesgo inherente. Para servidores de producción o entornos de servidor dedicado, descargue primero el script, inspecciónelo y luego ejecútelo:

“`bash

curl -o install_nvm.sh https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh

cat install_nvm.sh # review before running

bash install_nvm.sh

“`

Paso 3: Activar NVM en la sesión de shell actual

El instalador modifica su perfil, pero esos cambios solo tienen efecto en nuevas sesiones de shell. Para activar NVM inmediatamente sin abrir una nueva terminal:

Para Bash:

“`bash

source ~/.bashrc

“`

Para Zsh:

“`bash

source ~/.zshrc

“`

Carga manual (funciona en cualquier shell):

“`bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

“`

Problema común: archivo de perfil no cargado en shells no interactivos

En Ubuntu, `~/.bashrc` solo se carga para shells interactivos no de inicio de sesión. Si se conecta mediante SSH (un shell de inicio de sesión), Bash lee `~/.bash_profile` o `~/.profile` en su lugar. Si NVM no se encuentra después de iniciar sesión por SSH, añada el bloque de carga a `~/.bash_profile`:

“`bash

echo 'source ~/.bashrc' >> ~/.bash_profile

source ~/.bash_profile

“`

Este es uno de los problemas más frecuentes al configurar NVM en servidores remotos.

Paso 4: Verificar la instalación de NVM

“`bash

nvm –version

“`

Salida esperada (el número de versión puede variar):

“`

0.40.1

“`

Si el comando devuelve `nvm: command not found`, el perfil de shell no se cargó correctamente. Vuelva a ejecutar el comando de carga del Paso 3 y verifique que el bloque de inicialización existe en su archivo de perfil:

“`bash

grep -n 'NVM_DIR' ~/.bashrc

“`

Paso 5: Instalar Node.js usando NVM

Instalar la última versión LTS (recomendado para producción)

“`bash

nvm install –lts

“`

El indicador `–lts` instala la versión de soporte a largo plazo más reciente, que recibe parches de seguridad durante 30 meses. Para cargas de trabajo en producción en un VPS con cPanel o cualquier entorno de servidor, LTS es fuertemente preferida sobre la versión actual.

Instalar la última versión absoluta

“`bash

nvm install node

“`

Instalar una versión específica

“`bash

nvm install 20.14.0

“`

Listar todas las versiones remotas disponibles

“`bash

nvm ls-remote

“`

Para filtrar solo versiones LTS:

“`bash

nvm ls-remote –lts

“`

Paso 6: Verificar las versiones activas de Node.js y npm

“`bash

node -v

npm -v

“`

También confirme la ruta del binario para asegurarse de que no está usando accidentalmente una instalación de Node.js a nivel de sistema:

“`bash

which node

Expected: /home/<username>/.nvm/versions/node/v20.14.0/bin/node

“`

Paso 7: Gestionar múltiples versiones de Node.js

Listar todas las versiones instaladas localmente

“`bash

nvm ls

“`

Ejemplo de salida:

“`

-> v20.14.0

v18.20.3

v16.20.2

default -> lts/* (-> v20.14.0)

node -> stable (-> v20.14.0) (default)

lts/* -> lts/iron (-> v20.14.0)

“`

Cambiar entre versiones

“`bash

nvm use 18.20.3

“`

Este cambio solo se aplica a la sesión de terminal actual. Abrir una nueva terminal revierte a la versión predeterminada del alias.

Comprobar qué versión está activa actualmente

“`bash

nvm current

“`

Paso 8: Establecer una versión predeterminada persistente de Node.js

Para hacer que una versión específica sea la predeterminada para todas las nuevas sesiones de shell:

“`bash

nvm alias default 20.14.0

“`

También puede crear un alias para una línea de versión en lugar de una versión de parche específica, lo que rastrea automáticamente las actualizaciones dentro de esa línea:

“`bash

nvm alias default lts/*

“`

Paso 9: Automatizar el cambio de versión con `.nvmrc`

Esta es una de las funciones más potentes y menos utilizadas de NVM. Coloque un archivo `.nvmrc` en la raíz de su proyecto con la versión de Node.js requerida:

“`bash

echo "20.14.0" > /path/to/your/project/.nvmrc

“`

Luego, cuando haga `cd` en ese directorio:

“`bash

nvm use

Found '/path/to/your/project/.nvmrc' with version <20.14.0>

Now using node v20.14.0

“`

Cambio automático de versión al cambiar de directorio

Añada lo siguiente a su `~/.bashrc` (o `~/.zshrc`) para activar `nvm use` automáticamente cada vez que entre en un directorio que contenga un archivo `.nvmrc`:

Para Bash:

“`bash

cdnvm() {

command cd "$@" || return $?

nvm_path="$(nvm_find_up .nvmrc | command tr -d 'n')"

if [[ ! $nvm_path = *[^[:space:]]* ]]; then

declare default_version

default_version="$(nvm version default)"

if [[ $default_version == "N/A" ]]; then

nvm use default

elif [[ $(nvm current) != "$default_version" ]]; then

nvm use default

fi

elif [[ -r "$nvm_path/.nvmrc" && -r "$nvm_path" ]]; then

declare nvm_version

nvm_version=$(<"$nvm_path/.nvmrc")

declare locally_resolved_nvm_version

locally_resolved_nvm_version="$(nvm ls –no-colors "$nvm_version" | command tail -1 | command tr -d '->*' | command tr -d '[:space:]')"

if [[ "$locally_resolved_nvm_version" == "N/A" ]]; then

nvm install "$nvm_version"

elif [[ $(nvm current) != "$locally_resolved_nvm_version" ]]; then

nvm use "$nvm_version"

fi

fi

}

alias cd='cdnvm'

“`

Este patrón es especialmente valioso en pipelines de CI/CD y entornos de equipo donde múltiples desarrolladores trabajan en proyectos con diferentes requisitos de tiempo de ejecución.

Paso 10: Gestionar paquetes npm globales entre versiones

Cada versión de Node.js instalada por NVM tiene su propio directorio `node_modules` aislado para paquetes instalados globalmente. Esto significa que herramientas como `pm2`, `yarn` o `typescript` instaladas globalmente bajo `v18` no están disponibles bajo `v20`.

Instalar un paquete global para la versión activa

“`bash

npm install -g yarn

npm install -g pm2

npm install -g typescript

“`

Migrar paquetes globales al instalar una nueva versión

NVM proporciona un indicador integrado para copiar todos los paquetes globales de una versión a una nueva instalación:

“`bash

nvm install 20.14.0 –reinstall-packages-from=18.20.3

“`

Esto es fundamental al actualizar versiones de Node.js en un servidor que ejecuta procesos persistentes gestionados por PM2 o herramientas similares.

Listar paquetes instalados globalmente para la versión actual

“`bash

npm list -g –depth=0

“`

Paso 11: Desinstalar una versión de Node.js

Antes de desinstalar, cambie a otra versión distinta de la que desea eliminar:

“`bash

nvm use 20.14.0

nvm uninstall 16.20.2

“`

No puede desinstalar la versión activa actualmente. Intentarlo devuelve un error.

Avanzado: Usar NVM en entornos no interactivos (CI/CD, Cron, Systemd)

NVM depende de archivos de inicialización de shell que no se cargan en shells no interactivos. Esto provoca errores `node: command not found` en trabajos cron, archivos de unidad systemd y algunos entornos de CI.

Solución 1: Usar la ruta completa del binario

“`bash

/home/username/.nvm/versions/node/v20.14.0/bin/node /path/to/app.js

“`

Solución 2: Cargar NVM explícitamente en los scripts

“`bash

#!/bin/bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

nvm use 20.14.0

node /path/to/app.js

“`

Solución 3: Crear un enlace simbólico para acceso a nivel de sistema (usar con precaución)

“`bash

sudo ln -s /home/username/.nvm/versions/node/v20.14.0/bin/node /usr/local/bin/node

“`

Este enfoque sacrifica el aislamiento por usuario, pero a veces es necesario para servicios systemd que se ejecutan como un usuario de servicio dedicado.

NVM en alojamiento compartido vs. VPS vs. servidores dedicados

Para equipos que ejecutan aplicaciones Node.js junto con otros servicios, un VPS le proporciona el control a nivel de shell que NVM requiere sin la sobrecarga de gestionar hardware físico.

Lista de verificación de puntos clave prácticos

Úsela como referencia de implementación y configuración:

• Verifique el tipo de shell (`echo $SHELL`) antes de instalar — Zsh y Bash requieren diferentes archivos de perfil
• Use siempre `–lts` para instalaciones de Node.js en producción; reserve `node` (latest) para trabajo experimental
• Confirme `.nvmrc` en el control de versiones para que cada miembro del equipo y ejecutor de CI use la versión de tiempo de ejecución idéntica
• Use `–reinstall-packages-from` al actualizar versiones de Node.js para evitar reinstalar manualmente las herramientas globales
• Cargue NVM explícitamente en cualquier script no interactivo (cron, systemd, pipelines de CI) — nunca asuma que el perfil de shell ha sido cargado
• Audite los paquetes globales por versión con `npm list -g –depth=0` después de cambiar de versión para detectar dependencias faltantes a tiempo
• Fije versiones exactas en `.nvmrc` (p. ej., `20.14.0`) en lugar de aliases (p. ej., `lts`) para máxima reproducibilidad en producción
• Compruebe `which node` después de cambiar de versión para confirmar que no está usando accidentalmente un binario instalado en el sistema

Preguntas frecuentes

¿NVM requiere acceso sudo o root para instalar Node.js?

No. NVM instala todo bajo `~/.nvm` en el directorio de inicio del usuario actual. No se necesitan privilegios de root para instalar o cambiar versiones de Node.js. Esta es una de sus principales ventajas sobre los gestores de paquetes a nivel de sistema.

¿Por qué aparece `nvm: command not found` después de la instalación?

El bloque de inicialización de NVM se añadió a su perfil de shell, pero el perfil no ha sido recargado en la sesión actual. Ejecute `source ~/.bashrc` (Bash) o `source ~/.zshrc` (Zsh). Si el error persiste después de abrir una nueva terminal, compruebe que el bloque de inicialización fue realmente escrito en el archivo correcto usando `grep NVM_DIR ~/.bashrc`.

¿Pueden múltiples usuarios en el mismo servidor tener diferentes versiones de Node.js mediante NVM?

Sí. Dado que NVM se instala en el directorio de inicio de cada usuario (`~/.nvm`), cada usuario mantiene un conjunto completamente independiente de versiones de Node.js y paquetes globales. Esta es la arquitectura correcta para servidores multiusuario.

¿Qué ocurre con los paquetes npm instalados globalmente cuando cambio de versión de Node.js con NVM?

Cada versión de Node.js tiene su propio directorio de paquetes globales aislado. Los paquetes instalados globalmente bajo una versión no son visibles para otra. Use `nvm install <new-version> –reinstall-packages-from=<old-version>` para migrarlos automáticamente.

¿Es NVM adecuado para ejecutar aplicaciones Node.js en producción en un servidor?

NVM es muy adecuado para gestionar qué versión de Node.js se utiliza, pero para la gestión de procesos en producción debe combinarlo con un gestor de procesos como PM2 o usar archivos de unidad systemd. Asegúrese de que esos entornos no interactivos carguen NVM explícitamente o hagan referencia a la ruta completa del binario, como se describe en la sección de CI/CD anterior.