NodeJS

06 Jan 25 ⋅ 10 min

Instalação e Gerenciamento do Node.js com NVM

Q: Por que nvm use não vale para os outros terminais?

Porque ele altera o PATH só da sessão atual. Para definir o padrão de todo terminal novo, use nvm alias default 24.

Q: Dá para usar .nvmrc no Windows?

Não. O nvm-windows não lê .nvmrc. Se o time usa esse arquivo, no Windows a troca de versão continua manual, ou você roda tudo dentro do WSL.

Q: Qual versão do Node eu devo instalar?

A LTS, com nvm install --lts. Hoje é a v24.19.0. Versões Current recebem novidades antes, mas mudam mais rápido e nem toda biblioteca acompanha.

Q: O NVM funciona em Docker e CI?

Funciona, mas você precisa carregar o nvm.sh explicitamente — o .bashrc não roda em shell não interativo. Em imagem Docker, muita gente prefere partir da imagem oficial node:24 e pular o NVM.

Gregory Serrao

Como instalar o NVM no Linux, macOS e Windows e alternar entre versões do Node — com os comandos rodados num Ubuntu limpo.

Se você já apagou o Node.js pra instalar outra versão, ou já viu um projeto quebrar porque a sua máquina tinha a versão errada, o NVM resolve isso. Ele instala várias versões do Node lado a lado e troca entre elas com um comando.

Este guia cobre Linux, macOS e Windows, com os comandos rodados de verdade — não copiados de outro tutorial. Todas as saídas abaixo saíram de um Ubuntu 24.04 limpo, num container, em 15/08/2026.

Versões usadas aqui: NVM v0.40.6 (Linux e macOS) · nvm-windows 1.2.2 · Node LTS v24.19.0 (Krypton) · Node Current v26.7.0. Se você chegou aqui muito depois, confira a versão atual em github.com/nvm-sh/nvm antes de copiar o comando.

O que o NVM resolve

Sem gerenciador de versão, o Node é instalado no sistema inteiro. Um projeto que precisa da 18 e outro que precisa da 24 não convivem — você desinstala e reinstala toda vez que troca de projeto.

O NVM instala cada versão numa pasta separada dentro de ~/.nvm e muda o seu PATH na hora da troca. Cada versão vem com o npm correspondente, então você não mistura npm 10 com Node 24.

⚠️ Atenção a um detalhe que confunde muita gente: existem dois projetos diferentes com o nome NVM.

	quem usa	repositório
nvm	Linux e macOS	`nvm-sh/nvm`
nvm-windows	Windows	`coreybutler/nvm-windows`

Não são o mesmo programa, não têm os mesmos comandos e não compartilham código. O script de instalação com curl não funciona no Windows fora do WSL.

Linux (Ubuntu, Debian e derivados)

Antes de tudo: as dependências

Quase todo tutorial começa mandando rodar o curl. Num Ubuntu recém-instalado, isso falha:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh
bash: curl: command not found

O Ubuntu 24.04 não vem com curl. Instale primeiro:

sudo apt update
sudo apt install -y curl

Instalando o NVM

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

A saída termina assim:

=> Appending nvm source string to /root/.bashrc
=> Appending bash_completion source string to /root/.bashrc
=> Close and reopen your terminal to start using nvm or run the following to use it now:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

O instalador não instala o Node — ele instala só o gerenciador, e acrescenta três linhas no fim do seu ~/.bashrc.

Abra um terminal novo

Feche e abra o terminal, ou rode as três linhas que o próprio instalador imprimiu. Confira:

$ nvm --version
0.40.6

Se der command not found aqui, pule para a seção de problemas — tem uma causa específica e ela não é óbvia.

macOS

O caminho é o mesmo do Linux, com uma diferença que quebra a instalação de quem não presta atenção: desde o Catalina o shell padrão do macOS é o zsh, não o bash.

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

O instalador detecta o zsh e escreve no ~/.zshrc. Se você tiver os dois arquivos e ficar editando o ~/.bash_profile, vai mexer no arquivo errado. Confira em qual shell você está:

echo $SHELL     # /bin/zsh no macOS moderno

E o Homebrew?

Dá para instalar com brew install nvm, mas o Homebrew não configura o shell pra você — ele imprime as instruções e deixa o resto por sua conta. Além disso o Homebrew instala numa pasta própria, o que confunde a documentação oficial.

Para NVM, prefira o script curl. Guarde o Homebrew para o resto.

Windows

No Windows você usa o nvm-windows, que é outro projeto. Baixe o nvm-setup.exe da página de releases — a versão atual é a 1.2.2.

⚠️ Desinstale o Node antes. Se você já tem Node instalado pelo instalador oficial, remova pelo "Adicionar ou remover programas" antes de instalar o nvm-windows. Os dois brigam pelo mesmo PATH e o resultado é imprevisível.

Depois de instalar, abra um PowerShell ou Prompt novo (o PATH só atualiza em terminal novo) e confira:

nvm version

Os comandos são parecidos, mas não idênticos aos do nvm-sh:

tarefa	Linux/macOS	Windows
ver a versão do gerenciador	`nvm --version`	`nvm version`
instalar a LTS	`nvm install --lts`	`nvm install lts`
listar instaladas	`nvm ls`	`nvm list`
listar disponíveis	`nvm ls-remote`	`nvm list available`

O nvm-windows não suporta .nvmrc. Se o seu time usa esse arquivo, no Windows a troca continua manual.

A alternativa: WSL

Se você usa WSL, trate como Linux — instale o nvm-sh dentro da distribuição, e não o nvm-windows. São ambientes separados e cada um tem o seu Node.

Instalando o Node

Com o NVM funcionando, instale a LTS:

$ nvm install --lts
Computing checksum with sha256sum
Checksums matched!
Now using node v24.19.0 (npm v11.17.0)
Creating default alias: default -> lts/* (-> v24.19.0 *)

Repare em duas coisas: o npm veio junto, e o NVM criou um alias default — é a versão que abre em todo terminal novo.

Para uma versão específica, basta o número maior:

$ nvm install 22
Checksums matched!
Now using node v22.23.2 (npm v10.9.8)

Vendo o que está instalado

$ nvm ls
       v22.23.2 *
->     v24.19.0 *
default -> lts/* (-> v24.19.0 *)
node -> stable (-> v24.19.0 *) (default)
stable -> 24.19 (-> v24.19.0 *) (default)
lts/* -> lts/krypton (-> v24.19.0 *)

A seta -> marca a versão ativa naquele terminal. Abrir outra aba não herda a troca: cada terminal começa na default.

Os comandos que você vai usar

comando	o que faz
`nvm install 24`	instala a versão 24 mais recente
`nvm install --lts`	instala a LTS atual
`nvm use 22`	troca para a 22 neste terminal
`nvm alias default 24`	define qual versão abre por padrão
`nvm ls`	lista o que está instalado
`nvm ls-remote --lts`	lista as LTS disponíveis para baixar
`nvm current`	mostra a versão ativa agora
`nvm uninstall 18`	remove uma versão
`nvm run 22 app.js`	roda um arquivo numa versão sem trocar a atual

Fixando a versão do projeto com `.nvmrc`

Crie um arquivo .nvmrc na raiz do projeto com o número da versão:

echo "22" > .nvmrc

Agora, dentro da pasta:

$ nvm use
Found '/tmp/proj/.nvmrc' with version <22>
Now using node v22.23.2 (npm v10.9.8)

Commite esse arquivo. É a forma mais barata de garantir que todo mundo do time — e o CI — rode a mesma versão.

Trocando sozinho ao entrar na pasta

O nvm use ainda é manual. Para automatizar no zsh, acrescente ao ~/.zshrc:

autoload -U add-zsh-hook
carrega-nvmrc() {
  [ -f .nvmrc ] && nvm use --silent
}
add-zsh-hook chpwd carrega-nvmrc
carrega-nvmrc

Problemas comuns

`nvm: command not found` depois de instalar

O erro mais reportado, e a causa quase nunca é a que parece. Reproduzi num Ubuntu limpo:

$ source ~/.bashrc
$ nvm --version
bash: nvm: command not found

Recarreguei o .bashrc e mesmo assim não funcionou. O motivo está na primeira linha útil do arquivo:

$ head -6 ~/.bashrc
# If not running interactively, don't do anything
[ -z "$PS1" ] && return

O .bashrc do Ubuntu aborta logo no começo quando o shell não é interativo — e as linhas do NVM ficam no fim do arquivo. Ou seja: em script, em Dockerfile, em pipeline de CI e em qualquer bash -c, o NVM nunca chega a ser carregado.

A solução é carregar o nvm.sh diretamente, sem depender do .bashrc:

export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"

Verificado:

$ export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh"; nvm --version
0.40.6

Se você está num terminal comum e mesmo assim não funciona, confirme que as três linhas existem no fim do arquivo do shell que você realmente usa — ~/.bashrc no bash, ~/.zshrc no zsh.

O `node -v` mostra uma versão que você não instalou

Acontece quando existe um Node instalado pelo gerenciador de pacotes do sistema. Ele fica em /usr/bin/node e disputa o PATH com o do NVM.

Instalei o Node pelo apt no mesmo container para mostrar:

$ /usr/bin/node -v
v18.19.1

Com o NVM carregado, o dele ganha:

$ which node
/root/.nvm/versions/node/v24.19.0/bin/node
$ node -v
v24.19.0

Sem o NVM carregado, o do sistema volta:

$ which node
/usr/bin/node
$ node -v
v18.19.1

É o mesmo comando, na mesma máquina, com respostas diferentes — e é isso que faz o bug parecer fantasma. Sempre que a versão surpreender, rode which node antes de qualquer outra coisa: ele diz de onde o binário veio.

A solução definitiva é remover o Node do sistema e deixar só o do NVM:

sudo apt remove nodejs npm

A versão volta ao normal quando abro outro terminal

Não é bug: nvm use vale só para o terminal atual. Para mudar o padrão:

nvm alias default 24

O download está lento ou falhando

O NVM baixa binários do nodejs.org. Em rede corporativa com proxy, aponte o espelho:

export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

Vale a pena usar outra coisa?

O NVM é o mais usado e o mais documentado, mas é um script de shell — cada abertura de terminal custa alguns milissegundos a mais. Se isso te incomodar:

fnm — escrito em Rust, bem mais rápido, lê .nvmrc e usa comandos quase iguais.
Volta — fixa a versão no package.json em vez de um arquivo separado, e troca sozinho.
asdf / mise — se você já gerencia Python, Ruby e Go, um só gerenciador para tudo faz mais sentido.

Para quem está começando, fique com o NVM: quando você travar, a resposta que você achar no Google vai ser sobre ele.

Próximos passos

Com o Node instalado, o caminho natural é montar um projeto de verdade. Escrevi sobre como configurar uma API Node.js com TypeScript, e se você está decidindo qual versão adotar, o que mudou no Node.js 22 ajuda na escolha.

Perguntas frequentes

O NVM instala o npm junto?

Sim. Cada versão do Node traz o npm correspondente — a v24.19.0 vem com npm 11.17.0 e a v22.23.2 com npm 10.9.8. Você não precisa instalar o npm separado, e trocar de Node troca o npm junto.

Preciso desinstalar o Node antes de instalar o NVM?

No Linux e no macOS não é obrigatório, mas é recomendado: um Node em /usr/bin disputa o PATH e faz o node -v mostrar versão errada. No Windows é obrigatório — o nvm-windows conflita com o instalador oficial.

Por que `nvm use` não vale para os outros terminais?

Porque ele altera o PATH só da sessão atual. Para definir o padrão de todo terminal novo, use nvm alias default 24.

Dá para usar `.nvmrc` no Windows?

Não. O nvm-windows não lê .nvmrc. Se o time usa esse arquivo, no Windows a troca de versão continua manual, ou você roda tudo dentro do WSL.

Qual versão do Node eu devo instalar?

A LTS, com nvm install --lts. Hoje é a v24.19.0. Versões Current recebem novidades antes, mas mudam mais rápido e nem toda biblioteca acompanha.

O NVM funciona em Docker e CI?

Funciona, mas você precisa carregar o nvm.sh explicitamente — o .bashrc não roda em shell não interativo. Em imagem Docker, muita gente prefere partir da imagem oficial node:24 e pular o NVM.