Comment installer NVM pour Node.js sur Ubuntu : Guide technique complet

NVM (Node Version Manager) est un script shell conforme à POSIX qui installe et gère plusieurs environnements d’exécution Node.js isolés sur une seule machine, sans nécessiter de privilèges root ni modifier les chemins système. Chaque version de Node.js réside dans son propre répertoire sous `~/.nvm/versions/node/`, vous offrant une isolation complète et sans conflit entre les projets.

Ce guide présente une installation NVM de qualité production sur Ubuntu (20.04, 22.04 et 24.04), couvrant non seulement les commandes de base, mais aussi les cas particuliers des fichiers de profil shell, l’automatisation du flux de travail `.nvmrc`, la migration des paquets globaux et les pièges spécifiques aux serveurs que la plupart des tutoriels omettent.

Pourquoi NVM plutôt que le gestionnaire de paquets système

L’installation de Node.js via `apt` place un binaire unique à l’échelle du système dans `/usr/bin/node`. Sa mise à niveau affecte simultanément toutes les applications de l’hôte. Sur une machine de développement partagée ou un VPS exécutant plusieurs projets Node.js, cela crée des environnements fragiles et difficiles à reproduire.

NVM résout ce problème en installant chaque version de Node.js dans un répertoire utilisateur et en manipulant `PATH` au niveau du shell. Le résultat est un contrôle de version par utilisateur et par projet, sans aucun impact sur l’état des paquets du système d’exploitation.

NVM vs. autres gestionnaires de versions Node.js

NVM reste l’option la plus largement documentée et soutenue par l’écosystème, ce qui en fait la valeur par défaut la plus sûre pour les équipes et les environnements serveur où la reproductibilité importe davantage que la vitesse de démarrage brute.

Prérequis

• Ubuntu 20.04, 22.04 ou 24.04 (bureau ou serveur)
• Un compte utilisateur non-root avec les privilèges `sudo`
• `curl` ou `wget` installé (les deux sont présents par défaut sur la plupart des images Ubuntu)
• Familiarité de base avec Bash ou Zsh

Pour confirmer votre shell et votre version d’Ubuntu avant de commencer :

“`bash

echo $SHELL

lsb_release -a

“`

Étape 1 : Mettre à jour l’index des paquets système

Actualisez les listes de paquets APT pour vous assurer que toutes les dépendances résolues pendant la session sont à jour :

“`bash

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

“`

Confirmez également que `curl` est disponible :

“`bash

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

“`

Étape 2 : Télécharger et exécuter le script d’installation NVM

L’installateur officiel NVM est hébergé sur GitHub. Il clone le dépôt NVM dans `~/.nvm` et ajoute le bloc d’initialisation shell nécessaire à votre fichier de profil.

Option A — Avec curl (recommandé) :

“`bash

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

“`

Option B — Avec wget :

“`bash

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

“`

Vérifiez toujours le dernier tag de version sur la page des releases GitHub de NVM avant d’exécuter. Remplacez `v0.40.1` par le tag stable actuel si une version plus récente a été publiée.

Ce que fait réellement l’installateur :

1. Clone le dépôt NVM dans `~/.nvm`
2. Détecte votre shell actif (`bash`, `zsh`, `ksh` ou `fish`)
3. Ajoute le bloc d’initialisation suivant au fichier de profil approprié (`~/.bashrc`, `~/.zshrc`, `~/.profile` ou `~/.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"

“`

Note de sécurité : Rediriger un script distant directement dans `bash` est un schéma courant mais comporte des risques inhérents. Pour les serveurs de production ou les environnements de serveur dédié, téléchargez d’abord le script, inspectez-le, puis exécutez-le :

“`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

“`

Étape 3 : Activer NVM dans la session shell actuelle

L’installateur modifie votre profil, mais ces changements ne prennent effet que dans les nouvelles sessions shell. Pour activer NVM immédiatement sans ouvrir un nouveau terminal :

Pour Bash :

“`bash

source ~/.bashrc

“`

Pour Zsh :

“`bash

source ~/.zshrc

“`

Sourcing manuel (fonctionne dans n’importe quel shell) :

“`bash

export NVM_DIR="$HOME/.nvm"

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

“`

Piège courant : fichier de profil non sourcé dans les shells non interactifs

Sur Ubuntu, `~/.bashrc` n’est sourcé que pour les shells interactifs non-login. Si vous vous connectez via SSH (un shell login), Bash lit `~/.bash_profile` ou `~/.profile` à la place. Si NVM n’est pas trouvé après la connexion SSH, ajoutez le bloc de sourcing à `~/.bash_profile` :

“`bash

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

source ~/.bash_profile

“`

C’est l’un des problèmes les plus fréquemment rencontrés lors de la configuration de NVM sur des serveurs distants.

Étape 4 : Vérifier l’installation de NVM

“`bash

nvm –version

“`

Sortie attendue (le numéro de version variera) :

“`

0.40.1

“`

Si la commande retourne `nvm: command not found`, le profil shell n’a pas été sourcé correctement. Réexécutez la commande de sourcing de l’étape 3 et vérifiez que le bloc d’initialisation existe dans votre fichier de profil :

“`bash

grep -n 'NVM_DIR' ~/.bashrc

“`

Étape 5 : Installer Node.js avec NVM

Installer la dernière version LTS (recommandé pour la production)

“`bash

nvm install –lts

“`

Le flag `–lts` installe la version Long-Term Support la plus récente, qui reçoit des correctifs de sécurité pendant 30 mois. Pour les charges de travail en production sur un VPS avec cPanel ou tout environnement serveur, LTS est fortement préféré à la version actuelle.

Installer la toute dernière version

“`bash

nvm install node

“`

Installer une version spécifique

“`bash

nvm install 20.14.0

“`

Lister toutes les versions distantes disponibles

“`bash

nvm ls-remote

“`

Pour filtrer uniquement les versions LTS :

“`bash

nvm ls-remote –lts

“`

Étape 6 : Vérifier les versions actives de Node.js et npm

“`bash

node -v

npm -v

“`

Confirmez également le chemin du binaire pour vous assurer que vous n’utilisez pas accidentellement une installation Node.js à l’échelle du système :

“`bash

which node

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

“`

Étape 7 : Gérer plusieurs versions de Node.js

Lister toutes les versions installées localement

“`bash

nvm ls

“`

Exemple de sortie :

“`

-> 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)

“`

Basculer entre les versions

“`bash

nvm use 18.20.3

“`

Ce changement s’applique uniquement à la session de terminal actuelle. L’ouverture d’un nouveau terminal revient à l’alias par défaut.

Vérifier quelle version est actuellement active

“`bash

nvm current

“`

Étape 8 : Définir une version Node.js par défaut persistante

Pour faire d’une version spécifique la version par défaut pour toutes les nouvelles sessions shell :

“`bash

nvm alias default 20.14.0

“`

Vous pouvez également créer un alias vers une ligne de version plutôt qu’une version de correctif spécifique, ce qui suit automatiquement les mises à jour dans cette ligne :

“`bash

nvm alias default lts/*

“`

Étape 9 : Automatiser le changement de version avec `.nvmrc`

C’est l’une des fonctionnalités les plus puissantes et sous-utilisées de NVM. Placez un fichier `.nvmrc` à la racine de votre projet contenant la version Node.js requise :

“`bash

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

“`

Ensuite, lorsque vous faites `cd` dans ce répertoire :

“`bash

nvm use

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

Now using node v20.14.0

“`

Changement automatique de version lors du changement de répertoire

Ajoutez ce qui suit à votre `~/.bashrc` (ou `~/.zshrc`) pour déclencher `nvm use` automatiquement chaque fois que vous entrez dans un répertoire contenant un fichier `.nvmrc` :

Pour 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'

“`

Ce schéma est particulièrement utile dans les pipelines CI/CD et les environnements d’équipe où plusieurs développeurs travaillent sur des projets avec des exigences d’exécution différentes.

Étape 10 : Gérer les paquets npm globaux entre les versions

Chaque version de Node.js installée par NVM possède son propre répertoire `node_modules` isolé pour les paquets installés globalement. Cela signifie que des outils comme `pm2`, `yarn` ou `typescript` installés globalement sous `v18` ne sont pas disponibles sous `v20`.

Installer un paquet global pour la version active

“`bash

npm install -g yarn

npm install -g pm2

npm install -g typescript

“`

Migrer les paquets globaux lors de l’installation d’une nouvelle version

NVM fournit un flag intégré pour copier tous les paquets globaux d’une version vers une nouvelle installation :

“`bash

nvm install 20.14.0 –reinstall-packages-from=18.20.3

“`

C’est essentiel lors de la mise à niveau des versions de Node.js sur un serveur exécutant des processus persistants gérés par PM2 ou des outils similaires.

Lister les paquets installés globalement pour la version actuelle

“`bash

npm list -g –depth=0

“`

Étape 11 : Désinstaller une version de Node.js

Avant de désinstaller, basculez vers une autre version que celle que vous souhaitez supprimer :

“`bash

nvm use 20.14.0

nvm uninstall 16.20.2

“`

Vous ne pouvez pas désinstaller la version actuellement active. Toute tentative retourne une erreur.

Avancé : Utiliser NVM dans des environnements non interactifs (CI/CD, Cron, Systemd)

NVM repose sur des fichiers d’initialisation shell qui ne sont pas sourcés dans les shells non interactifs. Cela provoque des erreurs `node: command not found` dans les tâches cron, les fichiers d’unité systemd et certains environnements CI.

Solution 1 : Utiliser le chemin complet du binaire

“`bash

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

“`

Solution 2 : Sourcer NVM explicitement dans les 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

“`

Solution 3 : Créer un lien symbolique pour un accès à l’échelle du système (à utiliser avec précaution)

“`bash

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

“`

Cette approche sacrifie l’isolation par utilisateur mais est parfois nécessaire pour les services systemd s’exécutant en tant qu’utilisateur de service dédié.

NVM sur hébergement partagé vs. VPS vs. serveurs dédiés

Pour les équipes exécutant des applications Node.js aux côtés d’autres services, un VPS vous donne le contrôle au niveau du shell que NVM requiert, sans la charge de la gestion du matériel physique.

Liste de contrôle pratique des points clés

Utilisez ceci comme référence de déploiement et de configuration :

• Vérifiez le type de shell (`echo $SHELL`) avant l’installation — Zsh et Bash nécessitent des fichiers de profil différents
• Utilisez toujours `–lts` pour les installations Node.js en production ; réservez `node` (latest) pour les travaux expérimentaux
• Committez `.nvmrc` dans le contrôle de version afin que chaque membre de l’équipe et runner CI utilise la version d’exécution identique
• Utilisez `–reinstall-packages-from` lors de la mise à niveau des versions de Node.js pour éviter de réinstaller manuellement les outils globaux
• Sourcez NVM explicitement dans tout script non interactif (cron, systemd, pipelines CI) — ne supposez jamais que le profil shell a été chargé
• Auditez les paquets globaux par version avec `npm list -g –depth=0` après avoir changé de version pour détecter rapidement les dépendances manquantes
• Épinglez les versions exactes dans `.nvmrc` (ex. `20.14.0`) plutôt que des alias (ex. `lts`) pour une reproductibilité maximale en production
• Vérifiez `which node` après avoir changé de version pour confirmer que vous n’utilisez pas accidentellement un binaire installé par le système

Foire aux questions

NVM nécessite-t-il sudo ou un accès root pour installer Node.js ?

Non. NVM installe tout sous `~/.nvm` dans le répertoire personnel de l’utilisateur actuel. Aucun privilège root n’est nécessaire pour installer ou changer de version Node.js. C’est l’un de ses principaux avantages par rapport aux gestionnaires de paquets au niveau système.

Pourquoi `nvm: command not found` apparaît-il après l’installation ?

Le bloc d’initialisation NVM a été ajouté à votre profil shell, mais le profil n’a pas été re-sourcé dans la session actuelle. Exécutez `source ~/.bashrc` (Bash) ou `source ~/.zshrc` (Zsh). Si l’erreur persiste après l’ouverture d’un nouveau terminal, vérifiez que le bloc d’initialisation a bien été écrit dans le bon fichier en utilisant `grep NVM_DIR ~/.bashrc`.

Plusieurs utilisateurs sur le même serveur peuvent-ils chacun avoir des versions différentes de Node.js via NVM ?

Oui. Parce que NVM s’installe dans le répertoire personnel de chaque utilisateur (`~/.nvm`), chaque utilisateur maintient un ensemble complètement indépendant de versions Node.js et de paquets globaux. C’est l’architecture correcte pour les serveurs multi-locataires.

Que se passe-t-il avec les paquets npm installés globalement lorsque je change de version Node.js avec NVM ?

Chaque version de Node.js possède son propre répertoire de paquets globaux isolé. Les paquets installés globalement sous une version ne sont pas visibles par une autre. Utilisez `nvm install <new-version> –reinstall-packages-from=<old-version>` pour les migrer automatiquement.

NVM est-il adapté à l’exécution d’applications Node.js en production sur un serveur ?

NVM est bien adapté pour gérer quelle version de Node.js est utilisée, mais pour la gestion des processus en production, vous devriez l’associer à un gestionnaire de processus comme PM2 ou utiliser des fichiers d’unité systemd. Assurez-vous que ces environnements non interactifs sourcent explicitement NVM ou référencent le chemin complet du binaire, comme décrit dans la section CI/CD ci-dessus.