npm install 과 npm ci 의 차이

npm 이란

Node.js 환경에서 사용하는 패키지 관리자(package manager)로,

JavaScript 라이브러리의 설치, 버전 관리, 의존성 해결을 담당.

• npm은 Node Package Manager의 약자.

2024.09.08 - [utils] - [Summary] Package Manager

[Summary] Package Manager

---

Node.js 프로젝트에서 다음과 같은 작업들은 대부분 npm을 통해 이루어짐.

• 외부 라이브러리 설치
• 프로젝트가 의존하는 패키지들의 버전 관리
• 동일한 개발 환경의 재현
• CI 환경에서의 자동 설치

npm은 이러한 정보를 다음의 두 파일을 중심으로 관리:

• package.json
• package-lock.json

이 문서에서는

간단한, package.json 예시를 기준으로,

npm install 과 npm ci가

1. 어떤 정보를 바탕으로,
2. 어떤 버전을,
3. 왜 그렇게 설치하는지를 정리한다.

---

예제 package.json

다음은 vimwiki + github.io 에서 사용하는 데이터 생성용 Node.js 프로젝트의 package.json 임.

2026.01.14 - [utils] - johngrib의 vimwiki + github.io 를 설치하기

johngrib의 vimwiki + github.io 를 설치하기

2024.01.07 - [CE] - [Term] JSON (JavaScript Object Notation) :

[Term] JSON (JavaScript Object Notation) :

---

{
  "name": "johngrib.github.io",
  "version": "1.0.0",
  "description": "data generator",
  "main": "generateData.js",
  "dependencies": {
    "yamljs": "^0.3.0"
  },
  "scripts": {
    "test": "echo no test found"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/johngrib/johngrib.github.io.git"
  },
  "author": "John Grib",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/johngrib/johngrib.github.io/issues"
  },
  "homepage": "https://github.com/johngrib/johngrib.github.io#readme"
}

---

1. dependencies 항목의 의미

"dependencies": {
  "yamljs": "^0.3.0"
}

• dependencies는 이 프로젝트가 실행 시점(runtime)에 필요로 하는 외부 패키지를 선언하는 영역.
• 즉, 이 프로젝트는 실행되기 위해 yamljs라는 패키지가 반드시 필요함을 명시함.

---

참고: yamljs 이란?

yamljs는 JavaScript 환경에서 YAML 파일을 읽고(parse) 다루기 위한 경량 라이브러리이다.

2024.01.07 - [CE] - [Term] YAML (Yet Another Markup Language)

[Term] YAML (Yet Another Markup Language)

---

주요 용도는 다음과 같음.

• YAML 파일을 JavaScript 객체로 변환
• 설정 파일이나 문서 메타데이터를 YAML 형식으로 관리
• Node.js 환경에서 별도의 복잡한 의존성 없이 YAML 처리

이 프로젝트에서는 generateData.js에서

• YAML 기반의 문서 메타데이터를 읽어,
• Jekyll이 사용할 데이터로 변환하는 용도로 사용됨.

특징적인 점은 yamljs가 다른 npm 패키지에 대한 의존성이 거의 없는 단일 패키지라는 점임.
그래서 npm ls를 실행해도 설치된 패키지가 yamljs 하나만 표시된다.

---

2. 버전 범위 ^0.3.0의 의미

"yamljs": "^0.3.0"

이 표기는 Semantic Versioning(semver) 규칙에 따라 해석됨.

2024.09.19 - [Python] - [Etc] SW Version: Semantic Versioning + packaging.version

[Etc] SW Version: Semantic Versioning + packaging.version

---

^0.3.0은 다음 범위를 의미한다.

• 최소 버전: 0.3.0
• 최대 버전: 0.4.0 미만

즉, npm은 다음과 같은 버전들 중에서 선택할 수 있음.

• 0.3.0
• 0.3.1
• 0.3.2

반면 다음 버전들은 허용되지 않는다.

• 0.4.0
• 1.0.0

도구	문법 예시	설명
npm (YAML)	^0.3.0	0.3.0 이상 1.0.0 미만 (SemVer 캐럿)
Conda	yamljs >=0.3.0,<0.4.0	논리 연산자로 범위 지정
APT	yamljs (>= 0.3.0)	의존성 선언 시에만 제한적으로 사용되며 설치는 버전을 정확히 지정
PyPI (pip	yamljs~=0.3.0	~=(Tilde-equal)이 npm의 캐럿과 유사하게 동작

 

---

3. npm install은 무엇을 기준으로 버전을 설치하는가?

프로젝트 루트에서 다음 명령을 실행한다고 가정한다.

npm install

이때 npm은 다음 순서로 동작함:

1. package.json의 dependencies를 읽는다.
2. 각 패키지의 버전 범위 규칙을 해석한다.
3. npm registry에서 해당 범위에 속하는 버전들을 조회한다.
4. 그 중 가장 최신 버전 하나를 선택한다.
5. 선택된 버전을 node_modules/에 설치한다.
6. 설치 결과를 package-lock.json에 기록한다.

중요한 점은,

• npm install이 임의의 버전을 설치하는 것이 아니라
• 버전 범위 규칙에 따라 계산된 결과를 설치한다는 점이다.

---

4. package-lock.json이 있을 때의 동작

이미 package-lock.json이 존재하는 상태에서 npm install을 실행하면 동작이 조금 다름.

이 경우 npm은 다음과 같이 동작함:

• package.json의 버전 범위를 다시 계산하지 않는다.
• package-lock.json에 기록된 정확한 버전을 우선적으로 사용한다.
• 버전 범위를 벗어나지 않는 한, lock 파일의 내용을 그대로 따른다.

즉, package-lock.json이 있으면
npm install도 사실상 고정 버전 설치에 가까운 동작을 하게 된다.

---

5. npm ci 란?

npm ci의 ci는 Continuous Integration의 약자임.

Continuous Integration은 다음과 같은 환경을 전제로 함.

• 매번 동일한 소스 코드 기준으로
• 깨끗한 상태에서
• 자동화된 빌드와 테스트를 반복 수행

이를 위해 npm ci는 다음과 같은 특징을 가진다.

• package-lock.json이 반드시 필요
• package.json과 lock 파일이 조금이라도 다르면 에러
• 버전 범위 해석 및 재계산 과정 생략
• node_modules를 항상 삭제한 뒤 재설치

즉,

• npm install이 “허용 범위 내에서 적절한 버전을 선택”하는 명령이라면
• npm ci는 “이미 결정된 버전을 그대로 복원”하는 명령이다.

---

6. 사용 선택 기준

• 로컬 개발 환경
  • npm install 사용 가능
  • 필요 시 lock 파일 갱신
• CI, 자동 빌드, 재현성 중시 환경
  • package-lock.json 유지
  • npm ci 사용 권장

---

요약

• package.json은 허용 가능한 버전 범위를 정의하고,
• npm install은 그 범위 안에서 실제 버전을 결정하며,
• npm ci는 그 결정 결과를 그대로 재현한다.

---

같이보면 좋은 자료들

2024.09.08 - [utils] - [Summary] Package Manager

[Summary] Package Manager

---