Installer et utiliser NVM sur Windows, macOS et Linux.
Node Version Manager (NVM) est l’outil incontournable pour tout développeur JavaScript amené à travailler sur des projets aux exigences contradictoires en termes de version de Node.js. Plutôt que de jongler manuellement avec des installations globales, NVM vous permet d’installer, de basculer et de gérer plusieurs versions de Node.js en quelques commandes seulement.
L’installation de NVM diffère selon votre système d’exploitation. Windows utilise une version dédiée avec un assistant graphique, tandis que macOS et Linux exploitent la version originale via le terminal. Ce guide couvre toutes les plateformes et vous propose même plusieurs méthodes pour macOS, selon vos préférences.
Nettoyer son environnement avant l’installation
Avant toute chose, il est impératif de désinstaller toute version globale de Node.js qui pourrait être présente sur votre système. Si Node.js est déjà installé « en dur », il risque d’entrer en conflit avec NVM et de provoquer des comportements erratiques.
Sur Windows, ouvrez les Paramètres, puis Applications installées, cherchez Node.js et désinstallez-le. Pour être certain qu’il ne reste aucun résidu, ouvrez une invite de commandes et exécutez where node. Si un chemin s’affiche, supprimez manuellement le dossier correspondant, généralement situé dans C:Program Filesnodejs ou C:UsersVotreNomAppDataRoamingnpm.
Sur macOS et Linux, vous pouvez vérifier la présence d’une installation globale avec la commande which node. Si elle renvoie un chemin, désinstallez Node.js en utilisant la méthode qui a servi à l’installer (gestionnaire de paquets, installeur officiel, etc.). Cette précaution vous évitera de nombreux maux de tête par la suite.
Installation sur Windows 11 avec NVM for Windows
Windows dispose d’une version spécifique de NVM, appelée NVM for Windows, qui s’installe comme un logiciel classique via un assistant graphique.
Commencez par vous rendre sur la page officielle des releases du projet, à l’adresse github.com/coreybutler/nvm-windows/releases . Téléchargez le fichier nvm-setup.exe, qui correspond à la dernière version stable.
Avant de lancer l’installation, faites un clic droit sur le fichier et choisissez l’option « Exécuter en tant qu’administrateur ». Cette précaution est essentielle, car NVM doit créer un lien symbolique dans C:Program Files, une opération qui nécessite des droits élevés. Si vous omettez cette étape, l’installation semblera réussir, mais vous ne pourrez pas utiliser la commande node et passerez de longues minutes à chercher l’origine du problème.
L’assistant d’installation vous guide ensuite pas à pas. Acceptez la licence, puis choisissez le répertoire d’installation de NVM. Vous pouvez conserver le chemin par défaut (C:UsersVotreNomAppDataRoamingnvm) ou le personnaliser, à condition d’éviter les espaces et les caractères spéciaux qui pourraient causer des problèmes ultérieurs. L’étape suivante vous demande de définir le répertoire du lien symbolique Node.js. Laissez la valeur par défaut, à savoir C:Program Filesnodejs. C’est à cet endroit que NVM créera un raccourci vers la version active de Node.js, permettant à votre système de trouver la commande node sans effort.
Un point crucial que les mauvais tutoriels oublient de mentionner : l’installateur configure automatiquement les variables d’environnement NVM_HOME et NVM_SYMLINK. Vous n’avez donc rien à faire de ce côté-là, et surtout, ne tentez pas de les modifier manuellement. Certains guides vous conseillent de remplacer NVM_SYMLINK par le chemin d’une version spécifique, ce qui est une erreur grave : cela figerait NVM sur une version unique et l’empêcherait de changer dynamiquement. Cette variable doit toujours pointer vers C:Program Filesnodejs, et jamais vers un dossier comme C:...v16.20.2.
Une fois l’installation terminée, ouvrez une nouvelle fenêtre de terminal — car les variables d’environnement doivent être rechargées — et tapez nvm -v. Si un numéro de version s’affiche, l’installation est un succès.
Installation sur macOS et Linux avec la version originale de NVM
Sur macOS et Linux, on utilise la version originale de NVM, développée par la communauté et maintenue sur github.com/nvm-sh/nvm. Contrairement à la version Windows, l’installation se fait entièrement en ligne de commande, sans interface graphique.
Avant de commencer, assurez-vous que votre système dispose des outils nécessaires. curl ou wget sont généralement préinstallés, tout comme git. Sur macOS, il peut être nécessaire d’installer les Xcode Command Line Tools avec la commande xcode-select --install.
La méthode officielle, recommandée par l’équipe de NVM, consiste à exécuter un script d’installation directement depuis le terminal. La version la plus stable à ce jour peut être installée avec la commande suivante :
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
Si vous préférez utiliser wget, la commande équivalente est :
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
Ce script se charge de tout : il clone le dépôt NVM dans le dossier ~/.nvm, puis il ajoute automatiquement les lignes nécessaires à votre fichier de configuration de shell pour que NVM soit chargé à chaque ouverture de terminal. Selon votre shell, le script modifie ~/.bashrc, ~/.zshrc, ~/.profile ou un autre fichier approprié. C’est propre, efficace, et cela fonctionne dès la première fois.
Une fois le script exécuté, rechargez votre configuration pour que les modifications prennent effet immédiatement. Selon votre shell, utilisez source ~/.bashrc, source ~/.zshrc, ou si vous utilisez zsh sur macOS, le cas le plus fréquent, fermez simplement votre terminal et rouvrez-en un nouveau. La commande nvm --version vous confirmera alors que l’installation a réussi.
Installation alternative sur macOS avec Homebrew
Sur macOS, une autre méthode consiste à installer NVM via Homebrew, le célèbre gestionnaire de paquets. Cette approche peut séduire celles et ceux qui préfèrent centraliser toutes leurs installations avec un seul outil. Il faut cependant savoir que l’équipe officielle de NVM déconseille cette méthode, car elle peut générer des problèmes de permissions ou de chemins sur certaines configurations. À vous de décider si la praticité vaut le risque.
Si Homebrew n’est pas encore installé sur votre machine, commencez par exécuter la commande d’installation officielle :
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Une fois Homebrew prêt, installez NVM avec la commande :
brew install nvm
Cette commande télécharge et installe NVM, mais contrairement à la méthode par script, elle ne configure pas automatiquement votre environnement. Il vous faut donc créer le répertoire de NVM avec mkdir ~/.nvm, puis ajouter manuellement quelques lignes à votre fichier de configuration de shell, par exemple ~/.zshrc sur macOS. Voici les lignes à y ajouter :
export NVM_DIR="$HOME/.nvm"[ -s "$(brew --prefix nvm)/nvm.sh" ] && . "$(brew --prefix nvm)/nvm.sh"[ -s "$(brew --prefix nvm)/etc/bash_completion.d/nvm" ] && . "$(brew --prefix nvm)/etc/bash_completion.d/nvm"
La première ligne définit le répertoire où NVM stockera les versions de Node.js. La deuxième charge NVM à chaque ouverture de terminal. La troisième active la complétion automatique, qui vous suggère les commandes disponibles lorsque vous tapez nvm et appuyez sur la touche Tab.
Si vous utilisez un Mac équipé d’une puce Apple Silicon (M1, M2 ou M3), sachez que le chemin d’installation d’Homebrew diffère de celui des anciens Mac Intel. Sur ces machines, Homebrew s’installe dans /opt/homebrew. Heureusement, la commande $(brew --prefix nvm)/nvm.sh utilisée dans la configuration ci-dessus s’adapte automatiquement et renvoie le bon chemin, que vous soyez sur Intel ou Apple Silicon.
Après avoir modifié votre fichier de configuration, rechargez-le avec source ~/.zshrc, puis vérifiez l’installation avec nvm -v. Si tout s’est bien passé, la commande affiche le numéro de version installé.
Utilisation quotidienne de NVM
Une fois NVM installé, son utilisation est identique sur toutes les plateformes. Voici les commandes qui vont rythmer votre quotidien de développeur.
Pour installer une nouvelle version de Node.js, utilisez nvm install suivi du numéro de version. Par exemple, pour installer la version 18.20.4, tapez nvm install 18.20.4. Pour installer la dernière version LTS (Long Term Support), la plus recommandée pour la plupart des projets, utilisez nvm install --lts. NVM télécharge automatiquement la version demandée, la stocke dans son répertoire et la rend disponible.
Pour connaître toutes les versions que vous avez déjà installées sur votre machine, exécutez nvm list. La version actuellement active est signalée par une étoile à sa gauche, et une flèche indique la version par défaut si vous en avez définie une.
Pour basculer d’une version à une autre, la commande est nvm use suivie du numéro de version. Par exemple, nvm use 18.20.4 active cette version pour le terminal en cours. Vous recevez alors un message confirmant que Node.js utilise désormais cette version. Vous pouvez immédiatement vérifier avec node -v.
Enfin, il est pratique de définir une version par défaut, celle qui sera automatiquement chargée à chaque ouverture d’un nouveau terminal. Pour cela, utilisez nvm alias default suivi du numéro de version, par exemple nvm alias default 18.20.4. Ainsi, vous n’aurez pas à spécifier manuellement une version à chaque session.
Configurer Visual Studio Code pour qu’il utilise la bonne version
Votre terminal utilise la bonne version de Node.js grâce à NVM, mais qu’en est-il de votre éditeur de code ? Visual Studio Code, par exemple, possède son propre terminal intégré, qui peut hériter ou non des variables d’environnement de votre système selon la configuration.
Dans la plupart des cas, le terminal intégré de VSCode récupère automatiquement les variables d’environnement de votre shell, ce qui signifie qu’il utilisera la même version de Node.js que celle active dans votre terminal externe. Vous n’avez donc rien à faire.
Si toutefois vous constatez un décalage entre la version affichée dans le terminal externe et celle dans le terminal intégré de VSCode, une petite configuration dans les paramètres de l’éditeur peut résoudre le problème. Ouvrez la palette de commandes avec Ctrl+Maj+P ou Cmd+Maj+P, tapez Preferences: Open Settings (JSON), puis ajoutez cette ligne dans le fichier settings.json :
"terminal.integrated.env.windows": {"PATH": "${env:PATH}"}
Cette configuration est surtout utile sur Windows, où les variables d’environnement peuvent parfois ne pas être transmises correctement. Sur macOS et Linux, le terminal intégré hérite généralement du PATH de votre shell sans intervention. Redémarrez ensuite VSCode et ouvrez un terminal intégré pour vérifier avec node -v que la bonne version est bien utilisée.
Dépannage des problèmes courants
Même en suivant ce guide à la lettre, il arrive que des problèmes surviennent. Voici les plus fréquents et leurs solutions.
Si la commande node est introuvable après l’installation, le problème vient souvent d’un manque de droits administrateur lors de l’installation sur Windows. Dans ce cas, réexécutez l’installateur en tant qu’administrateur, ou ouvrez un terminal en tant qu’administrateur et utilisez nvm use pour forcer la recréation du lien symbolique.
Si vous avez suivi un mauvais tutoriel et modifié manuellement la variable NVM_SYMLINK pour qu’elle pointe vers une version spécifique, rétablissez-la immédiatement. Elle doit pointer vers C:Program Filesnodejs, et non vers un dossier comme C:...v16.20.2. Pour corriger la situation, ouvrez les Propriétés système, allez dans Variables d’environnement, modifiez NVM_SYMLINK pour lui redonner la valeur correcte, puis ouvrez un nouveau terminal.
Sur macOS ou Linux, si vous installez NVM avec Homebrew et que la commande nvm n’est pas trouvée, vérifiez que les lignes de configuration ont bien été ajoutées à votre fichier de shell et que vous avez rechargé votre configuration avec source ~/.zshrc ou l’équivalent pour votre shell. Si le fichier ~/.zshrc n’existe pas sur votre machine, créez-le avant d’ajouter les lignes.
Pour toute autre difficulté, le wiki du projet NVM for Windows à l’adresse github.com/coreybutler/nvm-windows/wiki recense une multitude de bugs connus et leurs solutions. Pour la version originale sur Unix, la documentation officielle et les issues GitHub sont également de précieuses ressources.
Ressources complémentaires
Pour approfondir vos connaissances et rester informé des évolutions, voici quelques liens utiles :
- Le dépôt officiel de NVM for Windows : github.com/coreybutler/nvm-windows
- Le dépôt officiel de NVM pour Unix : github.com/nvm-sh/nvm
- La page de téléchargement des versions de Node.js : nodejs.org/fr/download/prebuilt-installer
- D’autres gestionnaires de versions existent si NVM ne vous convient pas, comme Volta (volta.sh), asdf (asdf-vm.com) ou fnm, un gestionnaire léger écrit en Rust. Chacun a ses spécificités, mais NVM reste le plus répandu et le mieux documenté.
Que vous soyez sur Windows, macOS ou Linux, vous disposez désormais d’un environnement de développement flexible et propre, où basculer d’une version de Node.js à l’autre se fait en une fraction de seconde. Plus besoin de désinstaller puis réinstaller à chaque nouveau projet : NVM fait le travail pour vous, simplement et efficacement. Bon développement !
Aller plus loin avec la conteneurisation :
Après avoir configuré vos environnements de développement front-end, posez-vous la question de l’infrastructure locale et découvrezs si Docker Desktop et sa virtualisation sont réellement nécessaires pour vos projets web.
