Cómo instalar y configurar Node.js en Ubuntu con nodenv

Arranca la etapa de lenguajes de la serie, y empezamos por Node.js. En este artículo vas a aprender exactamente cómo instalarlo en Ubuntu o WSL con nodenv, un gestor de versiones que te deja tener varias versiones conviviendo sin conflictos.

Trabajo con proyectos que piden versiones distintas de Node: uno en la LTS actual, otro heredado que no puede moverse, un experimento con la más nueva. Instalar Node “a secas” con apt me funcionó hasta que dejó de hacerlo: la versión llegaba vieja y actualizarla rompía lo demás.

El problema es que la mayoría instala Node.js una sola vez, global y para siempre. Y el día que un proyecto pide otra versión, empiezan los parches: reinstalar, tocar el PATH a mano, o el clásico sudo npm que termina en errores de permisos.

Vamos a ver:

1. Instalar nodenv y su plugin node-build.
2. Configurar tu shell correctamente.
3. Instalar versiones de Node.js y elegir la global.
4. Fijar la versión por proyecto con .node-version.

Al final tendrás un entorno Node.js limpio, replicable y sin conflictos entre proyectos.

Tabla de contenidos

Paso 1: Verifica las dependencias

Si seguiste el setup profesional de la serie, ya tienes todo. Si llegaste directo a este artículo, esto es lo mínimo:

sudo apt update && sudo apt install -y git curl build-essential libssl-dev

Paso 2: Instala nodenv

Clona el repositorio en tu carpeta personal:

git clone https://github.com/nodenv/nodenv.git ~/.nodenv

Y su plugin node-build, que es el que aporta el comando nodenv install:

git clone https://github.com/nodenv/node-build.git ~/.nodenv/plugins/node-build

Sin node-build, nodenv sabe cambiar de versión pero no sabe instalarlas. Van juntos siempre.

Paso 3: Configura tu shell

Agrega nodenv al PATH y actívalo. Si usas zsh (el que configuramos con Oh My Zsh):

echo '' >> ~/.zshrc
echo '# Configuración de nodenv' >> ~/.zshrc
echo 'export PATH="$HOME/.nodenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(nodenv init - zsh)"' >> ~/.zshrc

Si usas bash, cambia ~/.zshrc por ~/.bashrc y zsh por bash en la última línea.

Aplica los cambios:

exec "$SHELL"

Verifica que quedó activo:

nodenv --version

Paso 4: Consulta las versiones disponibles

nodenv install -l

Ese comando lista las versiones estables recientes. Si quieres ver el catálogo completo, usa nodenv install -L.

Paso 5: Instala Node.js y define la versión global

Instala la versión que necesites (usa la LTS más reciente de la lista anterior):

nodenv install 24.1.0
nodenv global 24.1.0
nodenv rehash

• install descarga la versión.
• global la deja como predeterminada de tu máquina.
• rehash regenera los accesos a node, npm y npx; ejecútalo después de instalar versiones o paquetes globales.

Verifica:

node -v
npm -v
nodenv version

Paso 6: Fija la versión por proyecto

Aquí está la verdadera razón de usar nodenv. Dentro de la carpeta de un proyecto:

cd mi-proyecto
nodenv local 24.1.0

Esto crea un archivo .node-version en el proyecto: cada vez que entres a esa carpeta, nodenv activa esa versión automáticamente. Tu compañero de equipo clona el repo, corre nodenv install y trabaja con la misma versión que tú. Se acabaron los “en mi máquina funciona”.

Solución de problemas comunes

nodenv: command not found

La configuración del shell no quedó aplicada. Revisa que las líneas estén en el archivo correcto (~/.zshrc o ~/.bashrc) y reinicia la terminal.

Error de compilación al instalar una versión

Suele faltar alguna dependencia base:

sudo apt install -y build-essential libssl-dev

Instalé algo y el comando no aparece

Es el caso clásico de los shims:

nodenv rehash

Mantenimiento: actualiza nodenv y node-build

Ambos se actualizan con git:

cd ~/.nodenv && git pull
cd ~/.nodenv/plugins/node-build && git pull

Y para eliminar una versión de Node.js que ya no uses:

nodenv uninstall 24.1.0

Conclusión

Con nodenv instalado, una versión global sensata y .node-version en cada proyecto, Node.js deja de ser una fuente de conflictos: cada proyecto usa exactamente la versión que necesita y tu entorno se mantiene limpio y reproducible.

Si esto te fue útil, el artículo relacionado es el paso lógico: Setup Ubuntu y WSL para desarrollo profesional, la base de dependencias sobre la que nodenv compila sin sorpresas.

El martes publico esta misma configuración para macOS. Si no te lo quieres perder, suscríbete al newsletter en la portada del blog.

Recursos adicionales

• Instala y configura Git en Ubuntu
• Documentación oficial de nodenv
• Plugin node-build