npm과 패키지 관리

앞 글 Git 기초와 협업 워크플로우에서는 코드의 변경 이력을 관리하는 방법을 익혔습니다. 지금의 웹 개발은 직접 쓴 코드만으로 끝나지 않습니다. React나 Express 같은 프레임워크와 Axios, date-fns 같은 라이브러리를 함께 쓰므로, 외부 라이브러리를 관리하는 일이 꼭 필요합니다.

이때 쓰는 도구가 패키지 관리자(package manager)입니다. 패키지 관리자는 프로젝트가 의존하는 라이브러리를 설치하고 업데이트하고 지우며, 그 라이브러리가 다시 필요로 하는 다른 라이브러리까지 함께 관리합니다. Node.js 생태계에서 가장 널리 쓰이는 패키지 관리자가 npm(Node Package Manager)이며, 이 글에서는 npm의 기본 개념과 사용법, 그리고 같은 환경을 다시 만들 수 있게 패키지를 관리하는 방법을 정리합니다.

패키지와 npm

패키지(package)는 특정 기능을 하도록 미리 만들어 둔 코드 묶음, 즉 라이브러리나 프레임워크입니다. react, express, axios 모두 패키지이며, 대부분 다른 개발자가 공개한 오픈 소스라서 가져다 쓰면 개발 시간을 줄이고 검증된 기능을 쓸 수 있습니다. 패키지 관리자는 패키지를 찾고 설치하고 업데이트하고 지우는 과정을 자동화하며, 어떤 패키지가 동작하는 데 필요한 다른 패키지, 즉 의존성(dependency)도 함께 설치하고 관리합니다.

npm은 Node.js를 설치하면 함께 들어오는 기본 패키지 관리자이자, 세계에서 가장 큰 소프트웨어 레지스트리(registry) 가운데 하나입니다. 수백만 개의 자바스크립트 패키지가 npm 레지스트리에 등록되어 있습니다. npm으로 패키지를 설치하고(npm install), 지우고(npm uninstall), 허용한 버전 범위 안에서 업데이트하며(npm update), package.json에 적힌 의존성을 한꺼번에 설치할 수 있습니다. 또 package.json에 정의한 스크립트를 실행하고, 직접 만든 패키지를 레지스트리에 발행할 수도 있습니다.

package.json

package.json은 npm을 쓰는 모든 Node.js 프로젝트의 핵심 설정 파일로, 프로젝트의 정보와 의존성, 스크립트를 정의합니다.

npm install express

npm install nodemon --save-dev

위 그림은 프로젝트의 의존성을 쓰임에 따라 나눠 기록하는 모습입니다. package.json은 프로젝트가 요구하는 버전 범위를 적는 매니페스트(manifest)입니다. 서버가 요청을 처리할 때 쓰는 Express는 npm install express로 설치해 dependencies에 기록하고, 개발 중 서버를 다시 시작해 주는 nodemon이나 Jest, webpack 같은 테스트와 빌드 도구는 npm install nodemon --save-dev처럼 설치해 devDependencies에 기록합니다.

그림 아래쪽은 몇 가지를 더 짚습니다. 프로젝트가 요구한 패키지가 다시 다른 패키지를 요구하면 npm이 그 관계를 해결하므로, package.json에 적힌 이름 수만큼만 설치되는 것이 아닙니다. package.json이 요구 범위를 적는다면, package-lock.json은 실제로 해결된 정확한 버전과 의존성 트리를 기록합니다. peerDependencies는 함께 쓸 호스트 패키지의 호환 범위로 npm 7 이상은 기본으로 자동 설치하며, optionalDependencies는 설치에 실패해도 되는 의존성이라 빠져도 프로그램이 동작하게 만들어야 합니다. 그리고 어떤 필드에 적혔는지만으로 브라우저에 보낼 코드가 정해지지는 않으므로, 실제 import와 번들러 설정, 빌드 결과를 함께 확인합니다.

package.json 만들기

새 프로젝트를 시작할 때 npm init으로 package.json을 만듭니다. 다음 세 명령은 새 폴더를 만들어 이동한 뒤 그 폴더를 npm 프로젝트로 초기화합니다. npm init은 지금 있는 폴더에 package.json을 만들므로, 폴더를 옮기기 전에 실행하면 엉뚱한 곳에 파일이 생깁니다.

mkdir my-nodejs-app
cd my-nodejs-app
npm init

실행하면 프로젝트 이름, 버전, 설명 등을 묻는 질문이 나옵니다. 모든 질문에 기본값으로 답하려면 -y를 붙입니다.

npm init -y

다음은 만들어진 package.json에 설명용 값과 start 스크립트를 더한 예입니다. npm init이 이 내용을 그대로 만들어 주는 것은 아닙니다.

{
  "name": "my-nodejs-app",
  "version": "1.0.0",
  "description": "My first Node.js app",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node index.js"
  },
  "keywords": [],
  "author": "Your Name <[email protected]>",
  "license": "ISC",
  "dependencies": {},
  "devDependencies": {}
}

주요 필드

name은 프로젝트의 이름으로, npm 레지스트리에 발행한다면 겹치지 않아야 합니다. version은 지금 버전이며 보통 유의적 버전(semantic versioning, SemVer) 규칙을 따릅니다. main은 다른 코드가 require('my-nodejs-app')처럼 이 프로젝트를 모듈로 불러올 때 쓰는 진입 파일입니다. scripts는 자주 쓰는 명령을 정의하는 곳으로 npm run <이름>으로 실행하며, start와 test 같은 몇몇 스크립트는 run 없이 npm start, npm test로 실행할 수 있습니다.

dependencies는 프로젝트가 실제로 실행될 때 필요한 패키지이고, devDependencies는 개발하고 테스트하고 빌드할 때 필요한 패키지입니다. 완성된 결과물만 실행하는 환경에서는 보통 개발 의존성을 설치하지 않지만, 운영 서버라도 원래 소스에서 새로 빌드한다면 그 빌드 도구는 필요합니다.

npm 명령어

패키지 설치

실행에 필요한 패키지는 다음처럼 설치합니다. 세 줄은 차례로 패키지 이름만 적는 기본형, install을 i로 줄인 형태, @ 뒤에 버전 범위를 붙인 형태입니다. ^1.6.0이 어떤 버전까지 허용하는지는 아래의 유의적 버전 절에서 다룹니다.

npm install express    # express 패키지 설치 (latest 태그의 버전)
npm i react            # 'install'을 'i'로 줄여 쓸 수 있음
npm install axios@^1.6.0 # 지정한 버전 범위의 패키지 설치

설치한 패키지는 node_modules 폴더에 들어가고, package.json의 dependencies에 이름과 버전 범위가 자동으로 추가됩니다. 버전이나 태그를 적지 않으면 공개된 버전 가운데 가장 큰 번호가 아니라, 기본으로 레지스트리의 latest 태그가 가리키는 버전을 고르며, 지금의 npm과 Node.js에서 쓸 수 있는지도 확인합니다(npm install 문서).

개발할 때만 쓰는 패키지는 --save-dev나 -D를 붙여 설치하며, devDependencies에 추가됩니다.

npm install nodemon --save-dev
npm i jest -D # '--save-dev'를 '-D'로 줄여 쓸 수 있음

devDependencies는 테스트나 빌드처럼 개발 과정에서만 쓰는 도구라는 표시이므로, 배포할 환경에서는 설치하지 않도록 뺄 수 있습니다.

명령줄 도구처럼 시스템 전체에서 쓰려고 전역(global)으로 설치하는 패키지도 있습니다. -g를 붙이면 지금 프로젝트의 node_modules가 아니라 시스템의 전역 폴더에 설치되고, package.json에도 기록되지 않습니다.

npm install -g npm-check-updates

다만 전역 설치는 팀원마다 버전이 달라지기 쉬우므로 가급적 피하고, 프로젝트에 설치하거나 npx npm-check-updates처럼 npx로 바로 실행하는 방법을 먼저 씁니다.

프로젝트를 처음 내려받았거나 다른 개발자가 package.json에 의존성을 추가했다면, 다음 명령으로 적힌 의존성을 모두 설치합니다.

npm install # package.json에 명시된 모든 dependencies 및 devDependencies 설치

이 명령은 개발 의존성을 빼지 않은 기본 개발 환경을 가정합니다. NODE_ENV=production이거나 --omit=dev 옵션을 쓰면 개발 의존성을 설치하지 않을 수 있어, 잠금 파일에 webpack이 기록되어 있어도 그 환경의 node_modules에 실제로 있는지는 따로 확인해야 합니다. --include=dev로 명시하면 빼는 옵션보다 우선합니다.

패키지 제거와 업데이트

패키지를 지우면 node_modules와 package.json에서 함께 빠집니다. 두 번째 줄처럼 -D를 붙여도 되지만, npm uninstall은 패키지가 dependencies와 devDependencies 가운데 어디에 있든 찾아 지우고 package-lock.json의 기록도 함께 고칩니다.

npm uninstall express
npm uninstall jest -D

npm update는 package.json에 적힌 버전 범위 안에서만 패키지를 업데이트합니다. 업데이트할 수 있는 패키지는 npm outdated로 먼저 확인할 수 있습니다.

npm update # 모든 패키지를 package.json에 명시된 버전 범위 내에서 업데이트
npm update express # 특정 패키지 업데이트

유의적 버전과 범위

1.2.3 같은 버전 번호는 메이저.마이너.패치를 뜻합니다. 메이저는 호환되지 않는 변경, 마이너는 호환되는 기능 추가, 패치는 호환되는 버그 수정에 올립니다. 버전 범위 앞의 틸드(~)는 패치 업데이트까지만, 캐럿(^)은 마이너와 패치 업데이트까지 허용합니다.

두 표현 모두 시작 버전보다 작은 값은 허용하지 않는 하한도 있습니다. 안정 버전만 보면 ~1.2.3은 >=1.2.3 <1.3.0, ^1.2.3은 >=1.2.3 <2.0.0입니다. 캐럿은 0.x 버전에서 다르게 읽어, ^0.2.3은 >=0.2.3 <0.3.0, ^0.0.3은 >=0.0.3 <0.0.4입니다. 정식 출시 전 버전(prerelease)을 포함한 일반 규칙은 npm의 semver 문서에서 확인할 수 있습니다.

그래서 메이저 버전까지 올리려면 npm update가 아니라 npm install <패키지>@latest나 npm-check-updates 같은 도구를 써야 하며, 메이저 업데이트는 호환되지 않는 변경이 있을 수 있으니 변경 기록을 읽고 테스트합니다.

스크립트 실행

package.json의 scripts에 정의한 명령을 실행합니다. npm run 뒤에는 scripts의 키를 적으며, npm은 그 값에 적힌 명령을 실행합니다. 이때 프로젝트의 node_modules/.bin이 실행 경로에 더해지므로, 전역으로 설치하지 않은 도구 이름도 스크립트 안에서 바로 쓸 수 있습니다.

npm run test
npm run start # 'start' 스크립트는 'run' 생략 가능

이 예제의 test는 아직 테스트가 없다는 메시지를 출력하고 종료 코드 1로 끝나는 자리 표시자입니다. start를 쓰려면 실행할 index.js를 먼저 만들어야 합니다.

잠금 파일과 재현 가능한 설치

npm install을 실행하면 package-lock.json 파일이 자동으로 만들어집니다. 이 파일은 npm이 해결한 패키지들의 정확한 버전, 의존성 트리, 내려받을 주소 등을 기록합니다. 설치 옵션 때문에 디스크에 설치하지 않은 개발 의존성도 잠금 파일에는 기록될 수 있으므로, 지금의 node_modules와 항상 같지는 않습니다.

package.json의 ^1.2.3 같은 범위만으로 관리하면, 개발자마다 서로 다른 시점에 npm install을 실행해 다른 패치나 마이너 버전이 설치될 수 있습니다. package-lock.json은 해결된 정확한 버전을 기록해 이 차이를 막아 주므로 반드시 Git에 함께 커밋해야 합니다. 다만 잠금 파일만으로 모든 환경과 빌드 결과가 같아지는 것은 아니며, Node.js와 npm의 버전, 설치 옵션, 운영체제도 함께 관리합니다.

npm install express
# 또는 npm update express

npm ci
npm run build
npm test

위 그림은 의존성을 바꾸는 환경과, 이미 정한 조합을 다시 만드는 환경을 나눕니다. 위쪽의 흐름에서 동료나 CI 서버는 package.json과 잠금 파일을 받아 npm ci를 실행합니다. npm ci는 기존 잠금 파일이 있어야 하며, package.json의 요구와 잠금 파일이 맞지 않으면 새 버전을 고르는 대신 오류로 끝납니다. 맞으면 기존 node_modules를 지우고 잠금 파일 그대로 설치하며, 그 뒤 빌드와 테스트로 앱의 결과를 따로 확인합니다.

아래쪽의 변경 환경에서는 npm install express나 npm update express로 요구 범위에 맞춰 의존성을 해결하고, 바뀐 package.json과 잠금 파일을 검토한 뒤, 빌드와 테스트를 거쳐 두 파일을 함께 공유합니다. 재현 환경에서는 npm ci, npm run build, npm test를 실행하며 두 파일을 고치지 않습니다.

그림 아래의 설명처럼 두 파일이 맞지 않아 npm ci가 실패하면, 의도한 의존성 변경인지 확인하고 변경 환경에서 올바른 잠금 파일을 만들어 다시 검증합니다. 빌드나 테스트가 실패하면 설치 오류와 코드 오류를 구별해, 모든 실패를 의존성 업데이트로 해결하려 하지 않습니다. 설치가 성공했다고 앱까지 검증되었다고 보고하지 않는 것도 중요합니다(npm ci 문서).

webpack은 devDependencies에 있어도 브라우저용 결과물을 만드는 환경에는 꼭 필요합니다. 개발 의존성을 빼고 설치한 서버 실행 환경과, 원래 소스에서 새로 빌드하는 환경을 구별하세요. 반대로 dependencies에 적힌 패키지가 모두 브라우저로 전송되는 것도 아니며, 실제 import 관계와 번들 결과를 따로 확인합니다(package.json의 의존성 필드).

Yarn과 pnpm

Yarn은 Meta(예전 Facebook)가 만든 또 다른 자바스크립트 패키지 관리자로, npm과 비슷한 기능을 제공합니다. 병렬 처리와 캐시로 설치가 빠를 수 있고, yarn.lock에 의존성 버전을 기록하며, 이전에 내려받은 패키지를 캐시해 네트워크 없이도 설치할 수 있습니다. 명령은 조금 달라서 npm install <패키지>는 yarn add <패키지>, npm install -D <패키지>는 yarn add --dev <패키지>, npm uninstall은 yarn remove, npm run <스크립트>는 yarn <스크립트>입니다. 패키지를 한곳에 저장하고 연결해 디스크 공간을 아끼는 pnpm도 널리 쓰입니다.

npm이 꾸준히 발전해 도구 사이의 성능 차이는 많이 줄었습니다. 어느 도구를 쓰든 괜찮지만, 팀 안에서 같은 도구와 같은 잠금 파일을 일관되게 쓰는 것이 중요하며, 이 교재는 npm을 기본으로 씁니다.

더 깊이: 설치만 했는데 코드가 실행되는 이유

npm install은 파일을 내려받는 데서 끝나지 않습니다. Node.js 24와 26의 LTS에 함께 들어 있는 npm 11은 패키지의 package.json에 preinstall, install, postinstall 스크립트가 있으면 설치하는 동안 그 명령을 실행합니다. 설치하는 컴퓨터에 맞춰 네이티브 모듈을 컴파일하는 데 쓰라고 있는 기능이지만, 의존성의 의존성까지 포함해 내가 직접 고르지 않은 패키지의 코드도 설치 명령을 실행한 사용자의 권한으로 실행된다는 뜻입니다.

npm 문서도 install과 preinstall 스크립트는 되도록 쓰지 말라고 권하며, 이 둘을 쓸 정당한 경우는 설치하는 컴퓨터의 구조에 맞춰 컴파일해야 할 때뿐이라고 설명합니다. 설치할 때 스크립트를 아예 실행하지 않으려면 npm install --ignore-scripts처럼 옵션을 주거나 설정의 ignore-scripts를 켭니다. 다만 그러면 컴파일이 필요한 패키지가 제대로 동작하지 않을 수 있습니다.

pnpm은 버전 10부터, npm은 2026년 7월에 나온 버전 12부터 기본값을 바꿨습니다. 둘 다 의존성의 설치 스크립트를 기본으로 실행하지 않고, 프로젝트가 허용 목록에 적은 패키지만 실행합니다. npm 12에서는 npm install-scripts approve <패키지>가 이 목록을 package.json의 allowScripts 필드에 기록합니다. 같은 프로젝트라도 도구와 그 버전에 따라 설치할 때 실행되는 코드가 달라질 수 있으므로, 팀이 쓰는 도구의 기본값을 알아 두어야 합니다. npm의 스크립트 규칙은 npm의 scripts 문서에, npm 12의 허용 방법은 npm install-scripts 문서에 있습니다.

정리

• 패키지 관리자는 프로젝트가 의존하는 패키지와 그 패키지의 의존성까지 설치하고 관리하며, Node.js의 기본 도구는 npm입니다.
• package.json은 프로젝트의 정보와 스크립트, 요구하는 버전 범위를 적는 파일이고, 실행에 필요한 패키지는 dependencies, 개발과 빌드 도구는 devDependencies에 기록합니다.
• 버전을 적지 않은 설치는 latest 태그를 따르고, npm update는 ~나 ^로 정한 범위 안에서만 업데이트합니다.
• ^1.2.3은 >=1.2.3 <2.0.0이지만, 0.x 버전의 캐럿은 더 좁은 범위를 뜻합니다.
• package-lock.json은 해결된 정확한 버전을 기록하므로 Git에 커밋하고, 재현할 때는 두 파일이 맞아야 실행되는 npm ci를 씁니다.
• 필드의 분류와 브라우저로 가는 코드는 별개이며, 설치의 성공과 앱의 검증도 따로 확인합니다.

연습 문제

1. 범위에 들어가는 버전

안정 버전 1.2.2, 1.2.9, 1.3.0 가운데 ~1.2.3에 들어가는 것은 무엇일까요? ^0.2.3에는 0.2.9와 0.3.0 가운데 무엇이 들어갈까요? package.json의 요구 버전만 바꾸고 잠금 파일은 그대로 둔 채 npm ci를 실행하면, 새 조합을 자동으로 고를까요?

2. 잠금 파일과 업데이트

프로젝트가 ^1.2.3을 요구하고, 잠금 파일에는 1.2.8이 기록되어 있으며, 레지스트리에는 1.9.0과 2.0.0도 있습니다. npm ci로 설치하면 어떤 버전이 설치될까요? npm update로 범위 안에서 업데이트한다면 어떤 버전이 후보가 될까요?

3. 빌드 환경에서 빠진 도구

Express 서버와 webpack 빌드가 있는 프로젝트에서, 개발 의존성을 빼고 설치한 환경은 설치에 성공했습니다. 이 환경에서 원래 소스를 새로 번들링하려면 무엇이 빠졌을 수 있을까요? 또 이 글의 기본 package.json에서 npm test가 종료 코드 1을 냈다면, 어떤 테스트가 실패했다고 할 수 있을까요?

다음 글 Webpack 기초에서는 여러 자바스크립트와 CSS 파일을 브라우저가 쓰기 좋은 결과물로 묶어 주는 번들러 webpack의 기본 개념과 설정을 살펴봅니다.