Node.js nvm 오류 해결: command not found와 버전 전환 문제

nvm 오류는 설치보다 shell 설정과 PATH 확인이 먼저입니다

Node.js에서 nvm command not found가 뜨거나 nvm use를 실행했는데 node -v가 바뀌지 않는 문제는 대부분 설치 파일이 완전히 사라져서 생기는 오류가 아닙니다. 터미널이 nvm 로드 설정을 읽지 못했거나, 기존 Node.js 경로가 PATH 앞쪽에 남아 있거나, Mac·Windows·WSL·VSCode 터미널이 서로 다른 환경을 보고 있을 때 자주 발생합니다.

가장 먼저 아래 3가지를 확인하면 현재 상태를 빠르게 나눌 수 있습니다. node와 npm은 보이는데 nvm만 보이지 않으면 shell 설정 문제일 가능성이 높고, nvm use 뒤에도 node -v가 그대로라면 PATH 충돌이나 터미널 환경 차이를 의심해야 합니다.

node -v
npm -v
nvm --version

nvm command not found와 Node 버전 전환 오류를 shell 설정과 PATH 흐름으로 점검하는 이미지입니다.

자주 보이는 nvm 오류 메시지 원문

아래 메시지는 모두 nvm이 설치되지 않았거나, 설치되었더라도 현재 터미널 세션에서 nvm을 불러오지 못했거나, 선택한 Node 버전이 아직 설치되지 않았을 때 나타날 수 있습니다.

zsh: command not found: nvm

bash: nvm: command not found

'nvm' is not recognized as an internal or external command

N/A: version "xx" is not yet installed

nvm use를 했는데 node -v가 바뀌지 않는 상황

오류 문구만 보고 바로 재설치하기보다, 먼저 현재 터미널이 어떤 shell을 쓰는지, node와 npm이 어느 경로에서 실행되는지 확인하는 편이 안전합니다.

이 오류가 자주 발생하는 상황

nvm 오류는 설치 직후나 개발환경을 여러 방식으로 섞었을 때 많이 나타납니다. 특히 Mac에서 Homebrew Node와 nvm Node를 함께 설치했거나, Windows에서 공식 Node.js 설치본과 nvm-windows가 함께 남아 있거나, WSL과 Windows 터미널을 오가며 같은 환경이라고 생각할 때 헷갈리기 쉽습니다.

상황	가능한 원인	먼저 볼 것
nvm 설치 직후 명령어가 안 보임	터미널 재시작 또는 source 적용 누락	nvm --version, echo $SHELL
Mac zsh에서만 안 됨	~/.zshrc에 nvm 로드 설정 없음	cat ~/.zshrc
nvm use 뒤에도 버전이 그대로임	기존 Node 경로가 PATH 앞쪽에 있음	which node, where node
VSCode 터미널에서만 안 됨	VSCode 통합 터미널이 다른 shell 설정을 읽음	echo $SHELL, 기본 터미널 프로필
Windows와 WSL 결과가 다름	Windows Node와 WSL Node는 별도 환경	Windows 터미널인지 WSL 터미널인지

빠른 확인 명령어

Mac, Linux, WSL에서는 아래 명령어를 먼저 실행합니다. which nvm은 환경에 따라 결과가 비어 보일 수 있으므로, 함께 command -v nvm도 확인하면 좋습니다.

node -v
npm -v
nvm --version

which node
which npm
which nvm
command -v nvm

echo $SHELL
echo $PATH

Windows 명령 프롬프트나 PowerShell에서는 which 대신 where 또는 Get-Command를 사용합니다.

node -v
npm -v
nvm version
nvm list

where node
where npm
where nvm

Get-Command node
Get-Command npm
Get-Command nvm

원인은 보통 4가지로 좁혀집니다

1. nvm 로드 스크립트가 shell 설정 파일에 없음

macOS와 Linux 계열의 nvm은 실행 파일 하나만 PATH에 넣는 방식이 아니라, 터미널을 열 때 shell 설정 파일에서 nvm 스크립트를 불러오는 방식으로 동작합니다. 그래서 ~/.zshrc, ~/.bashrc, ~/.bash_profile에 nvm 로드 설정이 없으면 설치되어 있어도 command not found가 뜰 수 있습니다.

2. 터미널 재시작 또는 source 적용을 하지 않음

nvm 설치 스크립트가 설정 파일을 수정했더라도 이미 열려 있는 터미널에는 바로 반영되지 않을 수 있습니다. 이때는 터미널을 새로 열거나 source 명령으로 설정 파일을 다시 읽어야 합니다.

3. 기존 Node 설치 경로가 PATH 앞쪽에 있음

Homebrew, 공식 Node.js 설치 파일, nvm으로 설치한 Node가 함께 있으면 어떤 node가 먼저 실행될지 PATH 순서가 결정합니다. nvm use를 실행했는데도 node -v가 바뀌지 않으면 which node 또는 where node로 실제 실행 경로를 확인해야 합니다.

4. Windows, WSL, VSCode 터미널 환경이 서로 다름

Windows PowerShell, Windows 명령 프롬프트, WSL Ubuntu, VSCode Remote WSL 터미널은 서로 다른 환경일 수 있습니다. 한쪽에 nvm을 설치했다고 해서 다른 터미널에서도 자동으로 같은 명령어가 보이지는 않습니다.

Mac zsh에서 nvm command not found 해결 방법

최근 macOS에서는 zsh를 기본 shell로 쓰는 경우가 많습니다. 먼저 현재 shell이 zsh인지 확인합니다.

echo $SHELL

/bin/zsh가 보이면 ~/.zshrc를 확인합니다.

cat ~/.zshrc

아래 설정이 없으면 ~/.zshrc에 추가합니다.

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

설정 파일을 수정한 뒤에는 현재 터미널에 다시 적용합니다.

source ~/.zshrc
nvm --version

주의: PATH나 shell 설정 파일을 수정하기 전에는 기존 파일을 백업해 두는 편이 안전합니다. 아래 명령은 ~/.zshrc 백업 파일을 하나 만듭니다.

cp ~/.zshrc ~/.zshrc.backup-$(date +%Y%m%d-%H%M%S)

Homebrew로 설치한 Node와 nvm Node가 섞였는지도 확인합니다.

which node
node -v

결과가 /opt/homebrew/bin/node 또는 /usr/local/bin/node처럼 Homebrew 경로를 가리키고, nvm으로 선택한 버전이 반영되지 않는다면 PATH 우선순위가 꼬였을 수 있습니다. Node.js 설치 방식을 처음부터 정리하고 싶다면 Node.js 설치 3가지 비교: nvm, Homebrew, 공식 설치 선택 기준을 함께 확인하면 설치 방식을 나누는 데 도움이 됩니다.

주의: 아래 명령은 Homebrew로 연결된 Node 실행 경로를 해제할 수 있습니다. Homebrew Node에 의존하는 기존 프로젝트가 있다면 먼저 팀 문서나 프로젝트 README를 확인하세요.

brew list node
brew unlink node

그다음 터미널을 새로 열고 nvm과 Node 경로를 다시 확인합니다.

nvm --version
nvm use --lts
which node
node -v

bash 환경에서 해결하는 방법

bash를 사용하는 환경에서는 ~/.bashrc 또는 ~/.bash_profile을 확인합니다. 일반적으로 터미널을 열 때 읽는 파일이 다를 수 있으므로, 현재 shell과 설정 파일을 함께 확인하는 것이 좋습니다.

echo $SHELL
ls -a ~ | grep bash

~/.bashrc가 있다면 아래 설정이 들어 있는지 확인합니다.

cat ~/.bashrc

설정이 없다면 아래 내용을 추가합니다.

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

현재 터미널에 바로 반영합니다.

source ~/.bashrc
nvm --version

~/.bash_profile만 읽히는 환경이라면 ~/.bash_profile에서 ~/.bashrc를 불러오도록 구성하는 방식도 사용할 수 있습니다.

cat ~/.bash_profile

if [ -f ~/.bashrc ]; then
  . ~/.bashrc
fi

로그인 shell과 인터랙티브 shell은 시작할 때 읽는 설정 파일이 다를 수 있습니다. 그래서 OS 기본 터미널에서는 되는데 VSCode 터미널에서는 안 되거나, 반대로 VSCode에서는 되는데 새 로그인 shell에서는 안 되는 상황이 생길 수 있습니다.

Windows에서 nvm 오류를 해결하는 방법

Windows에서는 macOS·Linux용 nvm-sh가 아니라 nvm-windows를 쓰는 경우가 많습니다. 두 도구는 이름이 비슷하지만 같은 프로젝트가 아니며, 설정 방식과 동작 방식도 다릅니다.

먼저 새 명령 프롬프트 또는 PowerShell을 열고 nvm-windows가 잡히는지 확인합니다.

nvm version
nvm list
node -v
npm -v

'nvm' is not recognized as an internal or external command가 나온다면 nvm-windows가 설치되지 않았거나, 설치 경로가 Windows PATH에 반영되지 않았을 수 있습니다. 설치 직후라면 기존 터미널을 닫고 새로 여는 것만으로 해결되는 경우도 있습니다.

기존 Node.js 공식 설치본이 남아 있으면 nvm use를 실행해도 node -v가 바뀌지 않을 수 있습니다. 아래 명령으로 Node 실행 경로가 여러 개 잡히는지 확인합니다.

where node
where npm
where nvm

주의: 기존 Node.js 설치본을 제거하거나 PATH를 수정하기 전에는 전역 npm 설정과 프로젝트 의존성을 확인하세요. 회사 PC처럼 설치 권한이 제한된 환경에서는 임의로 삭제하지 말고 관리 정책을 먼저 확인하는 것이 안전합니다.

nvm-windows에서 버전 전환을 확인하는 기본 흐름은 다음과 같습니다.

nvm list
nvm install lts
nvm use lts
node -v
npm -v

관리자 권한이 필요한 경우와 필요 없는 경우도 나누어 볼 수 있습니다. nvm version, nvm list처럼 현재 상태를 보는 명령은 일반 터미널에서도 되는 경우가 많습니다. 반면 nvm use처럼 Windows의 Node symlink를 바꾸는 작업은 설치 위치와 권한 설정에 따라 관리자 권한 PowerShell 또는 명령 프롬프트가 필요할 수 있습니다.

nvm debug

nvm debug 결과에서 PATH 충돌이 보이면 기존 Node.js 설치 경로가 nvm-windows의 symlink보다 앞에 있는지 확인해야 합니다. 이때는 Windows 설정의 앱 목록, 시스템 환경 변수, where node 결과를 함께 비교합니다.

WSL에서 nvm이 안 잡힐 때 확인할 것

WSL의 Ubuntu 안에서 설치한 nvm은 WSL 터미널 안에서만 확인해야 합니다. Windows PowerShell에 nvm-windows가 설치되어 있어도 WSL Ubuntu 안에서는 별도 환경이며, 반대로 WSL에 nvm-sh를 설치했다고 해서 Windows 명령 프롬프트에서 바로 보이지 않습니다.

먼저 지금 터미널이 WSL 안인지 확인합니다.

uname -a
cat /etc/os-release
echo $WSL_DISTRO_NAME

WSL 안에서는 Ubuntu 기준으로 ~/.bashrc 또는 사용 중인 shell의 설정 파일을 확인합니다.

echo $SHELL
cat ~/.bashrc
cat ~/.zshrc

bash를 쓰고 있다면 ~/.bashrc에 아래 nvm 로드 설정이 들어 있는지 확인합니다.

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

수정 후에는 다시 읽습니다.

source ~/.bashrc
nvm --version
which node
node -v

VSCode Remote WSL을 쓰는 경우에는 VSCode 하단 상태 표시줄이 WSL 환경으로 연결되어 있는지 확인한 뒤, 통합 터미널에서 아래 명령을 실행합니다.

pwd
whoami
echo $WSL_DISTRO_NAME
which node
which npm
command -v nvm
nvm --version

which node 결과가 /mnt/c/Program Files/nodejs/처럼 Windows 경로를 가리킨다면 WSL 안에서 Windows Node가 먼저 잡히는 상태일 수 있습니다. 이 경우 WSL 안에서 설치한 nvm과 Node를 기준으로 PATH 순서를 정리하는 것이 좋습니다.

nvm use가 Node 버전을 바꾸지 못할 때

nvm use 오류는 선택하려는 버전이 아직 설치되지 않았거나, 설치되어도 현재 shell에서 다른 Node 경로가 먼저 잡히거나, 프로젝트의 .nvmrc와 실제 설치 버전이 맞지 않을 때 발생합니다.

먼저 설치된 버전을 확인합니다.

nvm list

N/A: version "xx" is not yet installed가 보이면 해당 버전을 먼저 설치합니다.

nvm install 20
nvm use 20
node -v

LTS 버전을 기준으로 쓰고 싶다면 아래처럼 확인할 수 있습니다.

nvm install --lts
nvm use --lts
node -v

새 터미널을 열 때 기본 Node 버전을 고정하려면 default alias를 설정합니다.

nvm alias default 20
nvm use default
node -v

프로젝트별로 Node 버전을 맞추려면 프로젝트 루트에 .nvmrc 파일을 둡니다.

cd your-project
echo "20" > .nvmrc
nvm install
nvm use
node -v

.nvmrc에는 팀이 사용하는 Node 주 버전이나 정확한 버전을 적습니다. 예를 들어 프로젝트가 Node 20 기준이라면 20을 넣고, 더 엄격하게 맞춰야 한다면 20.11.1처럼 적을 수 있습니다.

VSCode 터미널에서만 nvm이 안 보일 때

OS 기본 터미널에서는 nvm이 되는데 VSCode 통합 터미널에서만 안 보이면, 설치 문제보다 VSCode가 어떤 shell을 열고 있는지 확인해야 합니다.

먼저 VSCode를 완전히 종료한 뒤 다시 실행합니다. macOS에서는 창만 닫는 것이 아니라 앱을 종료해야 새 환경 변수가 반영되는 경우가 있습니다.

VSCode 통합 터미널에서 아래 명령을 실행합니다.

echo $SHELL
ps -p $$
node -v
npm -v
nvm --version
which node
command -v nvm

그리고 OS 기본 터미널에서도 같은 명령을 실행해 결과를 비교합니다. 두 결과에서 echo $SHELL, which node, echo $PATH가 다르면 VSCode가 다른 shell 또는 다른 PATH를 사용하고 있는 것입니다.

echo $PATH

VSCode의 기본 터미널 프로필이 zsh인지 bash인지 확인하고, 실제로 사용하는 shell의 설정 파일에 nvm 로드 설정이 들어 있는지 맞춰 봅니다. Mac에서 zsh를 쓰는데 ~/.bashrc만 수정했거나, WSL에서 bash를 쓰는데 Windows PowerShell 기준으로만 확인한 경우가 흔합니다.

재발 방지를 위한 설정 기준

nvm 오류를 반복하지 않으려면 설치 방식과 프로젝트 기준 Node 버전을 함께 정리해야 합니다. 개인 PC에서는 한 가지 Node 설치 방식을 중심으로 쓰고, 팀 프로젝트에서는 버전 기준을 저장소 안에 남겨 두는 편이 안전합니다.

• 프로젝트 루트에 .nvmrc 파일을 둡니다.
• README에 사용 Node 버전과 실행 순서를 적습니다.
• 팀 프로젝트에서는 package.json의 engines 항목도 함께 확인합니다.
• Homebrew Node, 공식 Node 설치본, nvm Node를 동시에 섞지 않도록 주의합니다.
• VSCode, OS 기본 터미널, WSL 터미널에서 같은 경로를 보고 있는지 비교합니다.

package.json에 Node 기준을 남기는 예시는 다음과 같습니다.

{
  "engines": {
    "node": ">=20 <21",
    "npm": ">=10"
  }
}

다만 engines는 프로젝트 기준을 알려 주는 역할에 가깝습니다. 실제 버전 전환은 nvm, nvm-windows, WSL 안의 nvm 설정이 정상적으로 동작해야 반영됩니다.

공식 자료로 더 확인하기

nvm 설치 명령, Windows용 도구 차이, Node.js와 npm 설치 기준은 시간이 지나면 달라질 수 있습니다. 아래 공식 자료에서 현재 권장 설치 방식과 사용법을 함께 확인하는 것이 좋습니다.

함께 보면 좋은 글

FAQ

nvm 오류는 재설치부터 시작하기보다 현재 터미널, shell 설정 파일, PATH 우선순위, Node 실행 경로를 차례대로 확인하는 방식이 가장 안전합니다.