npm (패키지 매니저)
npm은 JavaScript 프로젝트의 패키지를 설치하고 관리하며 프로젝트에 적힌 실행 명령을 부르는 도구입니다. package.json과 잠금 파일 및 실제 설치 폴더의 역할을 구분합니다.
같은 말:npm패키지 관리자
🤔 혹시 이런 경험 있나요?
AI가 만들어준 프로젝트를 열었는데, 다음과 같은 설치 안내를 볼 수 있습니다.
"터미널에서
npm install을 실행하세요."
시키는 대로 하면 뭔가 잔뜩 설치되고, node_modules라는 엄청나게 큰 폴더가 생깁니다. 도대체 뭘 설치한 건지, 왜 이렇게 많은 건지, 이 폴더를 지워도 되는 건지 궁금한 적 없나요?
🔑 패키지 매니저, 한마디로 뭘까요?
패키지 매니저는 다른 개발자가 만든 코드를 내 프로젝트에 쉽게 가져다 쓸 수 있게 해주는 도구입니다.
npm은 JavaScript와 Node.js 프로젝트에서 사용하는 패키지 관리자입니다. Node.js는 JavaScript를 브라우저 밖에서도 실행하는 프로그램입니다. 패키지(Package)란 누군가가 특정 기능을 미리 만들어놓은 코드 묶음을 말합니다.
🧱 레고 블록과 같습니다
집을 짓는다고 생각해보세요.
- 모든 걸 직접 만들기: 벽돌을 직접 굽고, 시멘트를 직접 만들고, 창문 유리를 직접 자르기
- 기성품 활용하기: 건축 자재점에서 벽돌, 시멘트, 창문을 사 와서 조립하기
프로그래밍도 마찬가지입니다. 로그인 기능, 날짜 계산, 이미지 최적화 같은 기능을 처음부터 만들 필요 없이, 이미 잘 만들어진 패키지를 가져다 쓰면 됩니다.
npm은 이 건축 자재점 역할을 합니다. npm 저장소에는 여러 개발자가 배포한 패키지가 있습니다. 등록돼 있다는 이유만으로 품질이나 안전성이 보장되지는 않으므로 프로젝트가 정한 이름과 버전을 확인합니다.
📦 핵심 파일과 폴더 이해하기
1. package.json - 재료 목록표
프로젝트의 이름과 실행 명령 및 필요한 패키지 목록 등을 적는 파일입니다.
{
"name": "npm-first-practice",
"private": true,
"scripts": {
"start": "node hello.js"
}
}위 예시는 외부 패키지 없이 hello.js를 실행하는 연습용 설정입니다. scripts는 이름으로 호출할 실행 명령을 적는 항목이고 private: true는 npm에 실수로 배포하는 것을 막는 설정입니다. 파일 공유나 GitHub 업로드까지 막지는 않습니다.
실제 프로젝트에는 실행에 필요한 dependencies와 개발 및 빌드 등에 쓰는 devDependencies가 있을 수 있습니다. 목록에 있는 패키지가 다른 패키지를 필요로 하면 함께 설치돼 폴더가 커집니다.
2. node_modules - 실제 재료 보관 창고
npm install을 실행하면 생기는 폴더입니다. package.json에 적힌 패키지들이 여기에 설치됩니다.
- 용량이 매우 큽니다 (수백 MB인 경우도 있습니다)
- 일반적인 프로젝트는 Git에서 제외하도록 .gitignore에 적습니다
- 기록된 의존성은 재설치할 수 있지만 이 폴더에 직접 고친 내용이나 따로 넣은 파일은 자동 복구되지 않습니다
3. package-lock.json - 정확한 버전 기록표
의존성은 프로젝트가 필요로 하는 다른 패키지입니다. 이 파일은 의존성의 정확한 버전과 관계를 기록해 재현 가능한 설치에 사용합니다. 운영체제와 Node.js 및 npm 버전과 접근 권한까지 모두 같게 만드는 것은 아닙니다.
- 삭제하지 마세요.
- npm을 쓰는 일반적인 앱 프로젝트는 소스와 함께 버전 관리합니다.
본문 개념을 설명하는 학습용 예시입니다. 실제 서비스 화면이 아닙니다. 실행 명령과 버전 범위는 프로젝트 설정을 따릅니다.
🛠️ 설치와 실행은 다릅니다
| 명령 | 하는 일 |
|---|---|
npm install | 프로젝트의 조건을 보고 의존성을 설치하며 잠금 파일이 바뀔 수 있습니다 |
npm ci | 잠금 파일에 맞춰 설치하며 설정과 맞지 않으면 멈춥니다 |
npm run | package.json에 등록된 실행 명령을 확인합니다 |
npm start | scripts의 start 명령을 실행합니다 |
npm run dev | scripts에 dev가 있을 때 해당 명령을 실행합니다 |
npm ci는 기존 node_modules가 있으면 지우고 다시 설치합니다. 설치에는 패키지가 제공하는 스크립트가 실행될 수 있으므로 모르는 프로젝트에서 무작정 실행하지 않습니다. 아래 첫 연습은 외부 패키지를 설치하지 않습니다.
⚡ npm과 yarn 및 pnpm
세 도구 모두 패키지를 관리하지만 명령과 잠금 파일 및 설치 방식이 다릅니다. 속도는 프로젝트와 환경에 따라 달라 고정 순위를 정하지 않습니다. 기존 프로젝트의 README와 packageManager 설정 및 잠금 파일을 확인하고 정해진 도구를 사용합니다. AI가 다른 명령을 제시했다고 중간에 관리자를 바꾸지 않습니다.
🔧 실행이 안 될 때
node --version과 npm --version은 설치된 버전을 확인하는 명령입니다. 명령을 찾을 수 없으면 설치 여부와 터미널 환경을 확인합니다. Node.js 공식 다운로드 안내에 운영체제별 방법이 있습니다. 이미 프로젝트가 요구하는 버전이 있다면 그 기준을 먼저 봅니다.
package.json이 없다는 오류는 현재 폴더를, Missing script 오류는 scripts의 명령 이름을 확인합니다. 패키지 충돌은 오류에 나온 이름과 버전을 확인하고 설치를 강제로 진행하거나 잠금 파일을 지우기 전에 프로젝트 조건과 대조합니다. 오류를 AI에 전달할 때 비밀 값은 가립니다.
📝 설치 없이 문장 하나 실행하기
Node.js와 npm이 이미 설치돼 있다면 연습 ZIP 받기를 내려받아 압축을 풉니다. 압축을 푼 폴더 안에서 package.json과 hello.js가 나란히 있는 위치를 확인합니다. 기존 프로젝트 파일 위에 풀지 않습니다.
터미널을 열고 cd 까지 입력한 뒤 그 폴더의 전체 경로를 따옴표로 감싸 입력합니다. Mac에서는 Finder에서 폴더를 터미널로 끌어 경로를 넣을 수도 있습니다. Windows PowerShell에서는 탐색기의 주소창에서 복사한 경로를 사용합니다. 이동 뒤 목록 명령으로 두 파일이 보이는지 확인합니다.
npm run
npm start첫 명령에 start가 있고 두 번째 결과에 모임 메모 연습이 보이면 실행 성공입니다. npm이 앞에 출력하는 프로젝트명과 실행 명령은 오류가 아닙니다. 외부 패키지가 없어 npm install은 필요하지 않습니다.
hello.js를 코드 편집기나 일반 텍스트 편집기로 엽니다. console.log("모임 메모 연습");는 괄호 안 문장을 화면에 출력하는 코드입니다. 따옴표와 괄호를 유지하고 안의 문자열만 다시 실행 성공으로 바꾸고 저장한 뒤 npm start를 반복합니다. 새 문장이 보이면 수정한 파일이 실행된 것입니다. 이전 문장이 보이면 저장 여부와 현재 폴더를 확인합니다. 다운로드한 파일이 hello.js.txt가 되지 않았는지도 확인합니다. Node.js가 없다면 두 파일을 읽어 실행 명령과 출력 문장의 관계부터 확인할 수 있습니다.
📋 3줄 요약
-
npm은 패키지를 관리하고 package.json에 등록된 실행 명령을 부르는 도구입니다.
-
잠금 파일은 의존성 버전과 관계를 기록하며 npm ci는 이 기록과 설정이 맞아야 설치합니다.
-
기존 프로젝트의 관리 도구를 유지하고 실행 오류는 현재 폴더와 설치 버전 및 scripts부터 확인합니다.
📚 참고 자료
공식 문서 확인: 2026년 10월 3일.

제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
npm을 쓰는 프로젝트에서 node_modules만 없어졌고 package.json과 일치하는 package-lock.json이 남아 있습니다. 프로젝트 안내대로 의존성을 다시 설치하는 방법은 무엇인가요?
예제나 확인 질문을 직접 시도한 뒤 완료 표시해요. 더 연습할 내용이 남으면 표시하지 않고 다음 글을 읽어도 됩니다. 완료 버튼은 이해도를 채점하지 않으며 잘못 표시하면 취소할 수 있어요.

