터미널에서 gulp 명령어를 실행했는데 gulp: command not found(명령을 찾을 수 없음) 오류가 발생한 적이 있으신가요? Gulp로 작업(task)을 실행하려다 이런 오류를 만나면 당황스러울 수 있습니다. 다행히 원인은 명확하고, 몇 가지 간단한 방법으로 금방 해결할 수 있습니다.
오류가 발생하는 이유
이 오류의 원인은 간단합니다. 어떤 디렉터리에서든 패키지를 명령줄에서 실행하려면 해당 패키지가 컴퓨터에 전역(globally)으로 설치되어 있어야 하기 때문입니다. 프로젝트 폴더에만 로컬로 설치되어 있다면 터미널은 gulp 명령어 자체를 인식하지 못합니다.
해결 방법 1: gulp-cli 전역 설치하기
Gulp를 정상적으로 사용하려면 두 가지 요소가 필요합니다.
- Gulp CLI가 전역으로 설치되어 있어야 합니다.
- Gulp 본체는 사용하는 각 프로젝트 디렉터리에 로컬로 설치되어야 합니다.
즉, 프로젝트 폴더에 Gulp를 설치하기 전에 반드시 먼저 Gulp CLI를 전역으로 설치해야 합니다. 다음 명령어를 입력하세요.
npm install gulp-cli -g
그다음, 실제로 Gulp를 사용할 프로젝트 디렉터리에서 아래 명령어로 Gulp를 설치합니다.
npm install gulp
해결 방법 2: npm 전역 디렉터리(/usr/local) 확인하기
Gulp CLI를 전역으로 설치했는데도 같은 오류가 계속 발생한다면, npm의 전역(global) 디렉터리가 잘못된 위치로 설정되어 있을 가능성이 큽니다. 전역 npm 디렉터리란 패키지를 전역으로 설치할 때 실제로 저장되는 위치를 의미합니다.
현재 설정된 위치를 확인하려면 명령줄에 다음을 입력하세요.
npm root -g
운영체제별 일반적인 경로는 다음과 같습니다.
- Windows(PC):
C:\Users\YOURNAME\AppData\Roaming\npm\node_modules - Mac:
/usr/local/lib/node_modules/
특히 Mac 사용자라면 주의해야 합니다. root 명령 실행 결과가 /Users/YOURNAME/node_modules처럼 홈 디렉터리 기준으로 나온다면, 이것이 바로 command not found 오류의 원인입니다.
npm prefix 설정 변경하기
이 경우 npm의 루트 폴더 설정을 올바른 위치로 변경하면 됩니다. 다음 명령어를 실행하세요.
npm config set prefix /usr/local
설정을 변경한 후에는 Gulp CLI를 전역으로, 그리고 Gulp를 프로젝트 디렉터리에 로컬로 다시 설치하세요. 이제 gulp 명령어가 오류 없이 정상적으로 실행될 것입니다.
정리
'gulp: command not found' 오류는 대부분 Gulp CLI가 전역으로 설치되지 않았거나, npm의 전역 설치 경로(prefix)가 잘못 설정되어 있는 것이 원인입니다. npm install gulp-cli -g로 CLI를 전역 설치하고, 문제가 지속되면 npm config set prefix /usr/local로 경로를 점검·수정하면 해결됩니다.