Node.js(NPM) 설치 및 NVM 버전 관리 가이드

# 개요

Node.js는 Chrome V8 JavaScript 엔진으로 빌드된 JavaScript 런타임(Runtime) 환경입니다.
브라우저 밖에서 JavaScript를 실행할 수 있게 해주며, 서버 개발뿐 아니라 프론트엔드 개발 도구를 사용하기 위해서도 반드시 필요합니다.

Node.js를 설치하면 NPM(Node Package Manager)이 함께 설치됩니다.
NPM은 JavaScript 패키지(라이브러리)를 설치하고 관리하는 도구로, 현대 웹 개발에서 필수적으로 사용됩니다.

Node.js는 LTS와 Current의 두 가지 버전을 제공합니다.
특별한 이유가 없다면 LTS 버전을 설치하는 것을 권장합니다.

# Node.js 설치

Node.js를 설치하는 방법은 크게 두 가지로, 공식 설치 프로그램을 사용하는 방법과 NVM(또는 NVM-Windows) 같은 버전 관리 도구를 사용하는 방법이 있습니다.
각 방법의 특징을 비교하면 다음과 같습니다.

# 공식 설치 프로그램

공식 설치 프로그램을 사용해서 Node.js를 설치하는 방법을 살펴봅시다.
간단하게 설치 프로그램을 다운로드하고 설치를 진행하면 됩니다.

만약 Node.js의 버전 관리가 필요하면 NVM이나 NVM-Windows를 사용하세요!

# macOS

LTS 버전의 macOS Installer(.pkg)를 다운로드합니다.

macOS Installer 다운로드

다운로드한 설치 파일을 실행하고 설치 마법사의 안내에 따라 진행합니다.

설치 마법사

설치가 완료되면 터미널에서 다음 명령어로 설치를 확인합니다.
설치 전에 이미 열려 있던 터미널에서는 반영되지 않을 수 있으므로, 터미널을 새로 열어서 확인하세요.

1
2
node -v # v24.19.0
npm -v # 11.17.0

# Windows

LTS 버전의 Windows Installer(.msi)를 다운로드합니다.

Windows Installer 다운로드

다운로드한 설치 파일을 실행하고 설치 마법사의 안내에 따라 진행합니다.

설치가 완료되면 터미널(CMD, PowerShell)에서 다음 명령어로 설치를 확인합니다.
설치 전에 이미 열려 있던 터미널에서는 반영되지 않을 수 있으므로, 터미널을 새로 열어서 확인하세요.

1
2
node -v # v24.19.0
npm -v # 11.17.0

이 경우 PowerShell에서 아래 명령어로 현재 사용자의 실행 정책을 변경하고, npm -v를 다시 실행하세요.
RemoteSigned는 직접 작성한 로컬 스크립트는 그대로 실행하고, 인터넷에서 내려받은 스크립트는 서명이 있어야 실행하는 정책입니다.

1
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # 확인 메시지가 표시되면 Y 입력

# NVM (macOS)

NVM(Node Version Manager)은 macOS와 Linux에서 여러 버전의 Node.js를 설치하고 전환할 수 있는 도구입니다.
버전 변경이 잦거나 여러 프로젝트에서 다른 Node.js 버전이 필요한 경우 매우 유용합니다.

다음 명령어를 복사해 터미널에 붙여넣고 실행하면 NVM이 설치됩니다.

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

Homebrew를 사용하는 경우, 다음 명령어로 NVM을 설치할 수 있습니다.

1
brew install nvm

설치 스크립트가 완료되면 셸 구성 파일(~/.zshrc, ~/.bashrc 등)에 다음과 같은 NVM 초기화 코드가 자동으로 추가됩니다.

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

다음 명령어로 구성을 불러와 확인하세요.
만약 구성이 없는 경우 직접 추가해야 합니다.

1
2
3
vim ~/.zshrc
# 혹은
vim ~/.bashrc

Vim 편집기로 접근한 후 다음 명령어로 내용을 확인하거나 수정할 수 있습니다.

1
2
3
4
5
6
7
# 내용 확인
:q ENTER # 저장 없이 종료

# 내용 수정
i # 입력 모드
ESC # 명령 모드
:wq ENTER # 저장 후 종료

그리고 NVM이 정상적으로 설치되었는지 확인합니다.

1
nvm -v # 0.40.7

이제 NVM을 사용해서 Node.js를 설치해봅시다.

1
2
nvm install 24 # 24버전 설치
nvm use 24 # 24버전 사용

설치가 완료되면 터미널에서 다음 명령어로 설치를 확인합니다.
설치 전에 이미 열려 있던 터미널에서는 반영되지 않을 수 있으므로, 터미널을 새로 열어서 확인하세요.

1
2
node -v # v24.19.0
npm -v # 11.17.0

# NVM-Windows

Windows에서는 NVM 대신 NVM-Windows를 사용합니다.
NVM-Windows는 원래의 NVM(macOS/Linux)과는 별개의 프로젝트이지만, 유사한 명령어로 Node.js 버전을 관리할 수 있습니다.

NVM-Windows Releases 페이지에 접속해 최신 버전의 nvm-setup.exe를 다운로드합니다.

설치 프로그램 다운로드

다운로드한 설치 파일을 관리자 권한으로 실행하고, 설치 마법사의 안내에 따라 진행합니다.
설치 경로는 자유롭게 지정하되, 기본값을 그대로 사용하는 것을 권장합니다.

설치 마법사

설치가 완료되면 터미널(CMD, PowerShell)을 새로 열어서 확인합니다.

1
nvm version # 1.2.2

설치 전에 이미 열려 있던 터미널에서는 반영되지 않을 수 있으므로, 터미널을 새로 열어서 확인하세요.
설치 후 해당 버전을 사용하도록 지정해야 합니다.

1
2
nvm install 24 # 24버전 설치
nvm use 24.19.0 # 24버전 사용

설치가 완료되면 터미널에서 다음 명령어로 설치를 확인합니다.
설치 전에 이미 열려 있던 터미널에서는 반영되지 않을 수 있으므로, 터미널을 새로 열어서 확인하세요.

1
2
node -v # v24.19.0
npm -v # 11.17.0

PowerShell에서 npm -v만 npm.ps1 파일을 로드할 수 없다는 오류가 발생하면, 다음 명령어로 실행 정책(Execution Policy)을 변경하고 다시 실행하세요.

1
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # 확인 메시지가 표시되면 Y 입력

# Node.js 제거

# macOS

공식 설치 프로그램으로 설치했다면, 터미널에서 다음 명령어를 실행해 제거합니다.

1
2
3
4
sudo rm -rf /usr/local/lib/node_modules
sudo rm -rf /usr/local/include/node
sudo rm /usr/local/bin/node
sudo rm /usr/local/bin/npm

NVM으로 설치한 경우에는, ~/.nvm 폴더를 삭제하면 NVM과 설치된 모든 Node.js 버전이 함께 제거됩니다.

1
rm -rf ~/.nvm

그리고 셸 구성 파일(~/.zshrc, ~/.bashrc 등)에서 다음과 같은 NVM 초기화 코드를 찾아 제거합니다.

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

변경 후 터미널을 새로 열어 명령어가 동작하지 않는지 확인합니다.

1
2
3
nvm -v # command not found: nvm
node -v # command not found: node
npm -v # command not found: npm

# Windows

설정(제어판) > 앱 > 앱 및 기능에서 Node.js 항목을 찾아 제거합니다.

그리고 다음과 같은 Node.js 관련 캐시 경로들을 확인해 삭제합니다.
NVM-Windows를 사용했다면, 관련 경로도 확인해 삭제합니다.

• C:\Program Files\nodejs
• C:\Users\{사용자명}\AppData\Roaming\npm
• C:\Users\{사용자명}\AppData\Roaming\npm-cache
• C:\Users\{사용자명}\.npmrc
• C:\Users\{사용자명}\AppData\Roaming\nvm
• C:\Users\{사용자명}\.nvm

마지막으로 환경 변수를 정리합니다.
Win + R을 눌러 sysdm.cpl을 입력하고 실행한 후, 고급 탭에서 환경 변수를 클릭합니다.

• 시스템 변수에서 다음 변수가 있으면 삭제합니다.
  • NODE_PATH
  • NVM_HOME (NVM-Windows)
  • NVM_SYMLINK (NVM-Windows)
• Path 변수에서 다음 경로를 찾아 제거합니다.
  • C:\Program Files\nodejs
  • %NVM_HOME% (NVM-Windows, 기본값: C:\Users\{사용자명}\AppData\Roaming\nvm)
  • %NVM_SYMLINK% (NVM-Windows, 기본값: C:\nvm4w\nodejs)

변경 후 터미널을 새로 열어 명령어가 동작하지 않는지 확인합니다.

1
2
3
4
5
nvm -v 
node -v 
npm -v
# 'xxx'은(는) 내부 또는 외부 명령, 실행 파일 또는 쉘 내장 명령이 아닙니다.
# 'xxx' 용어가 cmdlet, 함수, 스크립트 파일 또는 실행할 수 있는 프로그램 이름으로 인식되지 않습니다. 

# NVM 명령어

# .nvmrc

프로젝트 루트에 .nvmrc 파일을 생성하면, 해당 프로젝트에서 사용할 Node.js 버전을 명시할 수 있습니다.
팀원 간 Node.js 버전을 통일하거나 프로젝트별로 다른 버전을 관리할 때 유용합니다.

1
24

.nvmrc 파일이 있는 디렉토리에서 버전을 생략하고 nvm use 또는 nvm install을 실행하면, 파일에 명시된 버전이 자동으로 적용됩니다.

1
2
nvm use # .nvmrc에 명시된 버전으로 전환
nvm install # .nvmrc에 명시된 버전을 설치

.nvmrc 파일에는 다양한 형식으로 버전을 지정할 수 있습니다.