이 문서는 자바스크립트나 Node.js를 처음 다루는 분들도 어렵지 않게 따라올 수 있도록, nvm이라는 도구의 개념부터 실제 사용법까지 하나하나 풀어서 설명합니다. 명령어를 단순히 나열하는 대신, 왜 그런 명령어가 필요한지, 각 명령어가 실제로 무슨 일을 하는지 이야기하듯 정리했습니다.
Node.js로 여러 프로젝트를 하다 보면 곧 한 가지 골치 아픈 문제를 마주하게 됩니다. 어떤 프로젝트는 오래전에 만들어져서 Node.js 16에서만 정상적으로 돌아가고, 다른 프로젝트는 최신 문법을 쓰느라 Node.js 20이 필요한 식으로, 프로젝트마다 요구하는 Node.js 버전이 다르다는 점입니다. 컴퓨터에 Node.js를 하나만 설치해 두면 이런 상황에서 이러지도 저러지도 못하게 됩니다. 새 버전을 깔면 옛 프로젝트가 깨지고, 옛 버전을 유지하면 새 프로젝트를 못 하는 진퇴양난에 빠지는 것입니다.
nvm은 "Node Version Manager"의 줄임말로, 바로 이 문제를 해결하기 위해 태어난 도구입니다. 한 컴퓨터 안에 여러 버전의 Node.js를 나란히 설치해 두고, 상황에 따라 원하는 버전을 자유롭게 골라 쓸 수 있게 해 줍니다. 명령어 한 줄로 버전을 순식간에 바꿀 수 있고, 특정 폴더에 들어가면 그 프로젝트에 맞는 버전으로 자동으로 전환되게 할 수도 있습니다. 게다가 관리자 권한(sudo) 없이도 여러분의 홈 폴더 안에서 모든 것이 이루어지기 때문에 시스템을 건드릴 위험이 없어 안전합니다.
nvm이 관리하는 것은 Node.js 자체이며, Node.js를 설치하면 패키지 관리자인 npm도 함께 따라옵니다. 그래서 Node.js 버전을 바꾸면 그에 맞는 npm 버전도 함께 바뀐다는 점을 알아 두면 좋습니다.
참고로 이 문서에서 다루는 nvm은 macOS와 Linux용입니다. 윈도우를 쓴다면 이름이 비슷한 별도의 프로젝트인
nvm-windows를 사용해야 하며, 명령어가 조금 다릅니다.
nvm은 공식에서 제공하는 설치 스크립트를 실행하는 것이 가장 간편합니다. 터미널을 열고 아래 명령을 실행하면 됩니다.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash또는 curl 대신 wget을 써도 됩니다.
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash위 주소에 있는 v0.40.1은 nvm의 버전입니다. 시간이 지나면 더 새로운 버전이 나올 수 있으니, 최신 버전 번호는 nvm 공식 저장소에서 확인해 사용하는 것이 가장 정확합니다.
이 스크립트는 nvm을 여러분의 홈 폴더 안 ~/.nvm 위치에 내려받고, 셸 설정 파일(zsh를 쓴다면 ~/.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"간혹 스크립트가 이 줄을 넣어 주지 못하는 경우가 있으니, 나중에 nvm 명령이 인식되지 않는다면 위 내용이 셸 설정 파일에 들어 있는지 확인해 보면 됩니다.
스크립트 실행이 끝나면, 변경 사항이 반영되도록 터미널을 완전히 껐다 켜거나 아래 명령으로 설정을 다시 불러옵니다.
source~/.zshrc그런 다음 아래 명령을 실행했을 때 nvm이라는 글자가 출력되면 설치가 제대로 된 것입니다.
command -v nvmnvm으로 설치할 수 있는 Node.js 버전은 아주 많습니다. 전체 목록을 보려면 다음과 같이 입력합니다.
nvm ls-remote목록이 무척 길기 때문에, 보통은 원하는 부분만 걸러서 보는 편이 편합니다. 예를 들어 20 버전대만 보고 싶다면 이렇게 합니다.
nvm ls-remote | grep v20Node.js 버전 중에는 이름 옆에 "LTS"라는 표시가 붙은 것들이 있습니다. LTS는 "Long Term Support", 즉 오랜 기간 안정적으로 지원되는 버전이라는 뜻입니다. 실무나 실제 서비스에서는 대체로 이 LTS 버전을 쓰는 것이 안전합니다.
원하는 버전을 찾았다면, 그 번호를 그대로 적어 설치합니다.
nvm install 20.11.1정확한 세부 번호를 일일이 적기 번거롭다면, 큰 버전 번호만 적어도 됩니다. 그러면 해당 버전대의 최신판이 설치됩니다.
nvm install 20가장 최신 LTS 버전을 설치하고 싶다면 아래처럼 하면 편리합니다.
nvm install --lts새 버전을 설치하면 nvm은 대개 그 버전을 곧바로 현재 사용 버전으로 활성화해 줍니다.
지금까지 설치한 버전들의 목록은 다음 명령으로 확인할 수 있습니다. 현재 활성화되어 있는 버전은 화살표(->)로 표시됩니다.
nvm ls지금 이 순간 실제로 어떤 버전이 쓰이고 있는지만 간단히 알고 싶다면 이렇게 합니다.
nvm current더 이상 쓰지 않는 버전은 지워서 공간을 정리할 수 있습니다. 단, 지금 사용 중인 버전은 지울 수 없으니 다른 버전으로 먼저 전환한 뒤 삭제해야 합니다.
nvm uninstall 20.11.1nvm을 진짜 유용하게 만들어 주는 부분이 바로 여기, 버전을 바꾸는 기능입니다.
여러 버전을 설치해 두었다면, 언제든 아래 명령으로 원하는 버전으로 갈아탈 수 있습니다.
nvm use 18이렇게 하면 지금 열려 있는 터미널에서 node 명령이 곧바로 18 버전을 가리키게 됩니다. 다만 여기서 꼭 알아 두어야 할 점이 하나 있습니다. nvm use로 정한 버전은 지금 이 터미널 창에서만, 그리고 이 창을 닫기 전까지만 유효하다는 것입니다. 새 터미널 창을 열면 다시 기본 버전으로 돌아갑니다.
매번 터미널을 열 때마다 버전을 지정하기는 번거롭습니다. 그래서 새 터미널을 열 때 자동으로 적용될 기본 버전을 정해 둘 수 있습니다. 아래처럼 default라는 이름표를 붙여 주면 됩니다.
nvm alias default 20이제부터 새 터미널을 열면 언제나 20 버전이 준비되어 있습니다. nvm install로 처음 설치한 버전이 자동으로 기본값이 되기도 하지만, 명시적으로 정해 두는 편이 확실합니다.
pyenv를 써 본 분이라면 익숙할 만한 기능입니다. 프로젝트 폴더 안에 .nvmrc라는 작은 파일을 하나 만들어 두고, 그 안에 원하는 버전 번호를 적어 둘 수 있습니다.
cd my-project
echo"18.19.0"> .nvmrc이제 이 폴더 안에서 아래 명령을 실행하면, nvm이 .nvmrc 파일을 읽어 자동으로 그 버전으로 전환해 줍니다.
nvm use이 .nvmrc 파일을 프로젝트와 함께 Git 저장소에 올려 두면, 같은 프로젝트를 내려받은 동료들도 nvm use 한 번이면 정확히 같은 Node.js 버전을 쓰게 됩니다. 팀원끼리 버전을 맞추느라 애먹을 일이 사라지는 셈입니다.
폴더에 들어가기만 해도 nvm use를 자동으로 실행하게 만드는 방법도 있지만, 이는 셸 설정에 추가 스크립트를 넣어야 하므로 익숙해진 뒤에 nvm 공식 문서를 참고해 설정하기를 권합니다.
새로운 Node.js 버전으로 넘어갈 때, 예전 버전에 전역(global)으로 설치해 두었던 npm 패키지들을 다시 일일이 설치하기는 번거롭습니다. nvm은 이럴 때 예전 버전에 깔려 있던 전역 패키지들을 새 버전으로 함께 옮겨 주는 편리한 기능을 제공합니다.
nvm install 20 --reinstall-packages-from=18이 명령은 20 버전을 설치하면서, 18 버전에 전역으로 깔려 있던 패키지들을 자동으로 새로 설치해 줍니다.
특정 버전으로 딱 한 번만 명령을 실행하고 싶을 때, 굳이 버전을 전환하지 않고도 아래처럼 지정해서 실행할 수 있습니다.
nvm run 18 --version
nvm exec 18 node app.jsnvm run은 지정한 버전의 node로 곧바로 실행하고, nvm exec는 지정한 버전 환경에서 임의의 명령을 실행합니다.
특정 버전의 node 실행 파일이 실제로 어디에 있는지 궁금하다면 아래 명령이 그 경로를 알려 줍니다.
nvm which 20터미널을 새로 열었더니 nvm: command not found가 나옵니다.
nvm은 프로그램이 아니라 셸에 불러들여지는 스크립트라서, 셸 설정 파일에서 nvm을 불러오는 줄이 빠져 있으면 인식되지 않습니다. 앞의 설치 항목에서 소개한 세 줄이 ~/.zshrc(또는 ~/.bashrc)에 들어 있는지 확인하고, source ~/.zshrc를 실행해 보세요.
nvm use로 버전을 바꿨는데, 새 터미널을 여니 다시 원래대로 돌아옵니다.
이는 오류가 아니라 원래 그렇게 동작하는 것입니다. nvm use는 그 터미널에서만 유효합니다. 모든 터미널에 적용될 기본 버전을 정하려면 nvm alias default <버전>을 사용하세요.
node는 새 버전인데 전역으로 설치했던 명령어가 사라졌습니다.
전역 패키지는 Node.js 버전마다 따로 관리됩니다. 버전을 바꾸면 그 버전에 설치된 패키지만 보입니다. 앞서 소개한 --reinstall-packages-from 옵션으로 패키지를 함께 옮겨 오면 해결됩니다.
| 하고 싶은 일 | 명령어 |
|---|---|
| 설치 가능한 버전 목록 보기 | nvm ls-remote |
| 특정 버전 설치 | nvm install 20.11.1 |
| 최신 LTS 설치 | nvm install --lts |
| 설치된 버전 목록 | nvm ls |
| 현재 쓰는 버전 확인 | nvm current |
| 버전 전환 (이 터미널만) | nvm use 18 |
| 기본 버전 지정 | nvm alias default 20 |
| .nvmrc 따라 전환 | nvm use |
| 버전 삭제 | nvm uninstall 20.11.1 |
| 패키지 함께 옮기며 설치 | nvm install 20 --reinstall-packages-from=18 |
| 실제 실행 경로 확인 | nvm which 20 |
이 정도만 익혀 두어도 일상적인 Node.js 개발에서 버전 관리로 곤란할 일은 거의 없을 것입니다. 처음에는 install, use, alias default 세 가지만 확실히 잡고, 프로젝트가 늘어나면 .nvmrc로 넓혀 가는 순서로 익히기를 권합니다.