Tailwind CSS v4: "could not determine executable to run" 에러 원인과 해결 방법
Problem
새로운 프로젝트를 시작하면서 평소처럼 Tailwind CSS를 설치하고 tailwind.config.js 파일을 생성하기 위해 npx tailwindcss init -p 명령어를 실행하는 경우가 많습니다. 하지만 최근 이 명령어를 실행하면 npm error could not determine executable to run이라는 예상치 못한 에러가 발생합니다. 분명히 패키지를 설치했음에도 불구하고 npm이 실행할 파일을 찾지 못해 당황스러울 수 있습니다. 이는 기존에 잘 작동하던 방식이 갑자기 동작하지 않아 많은 프론트엔드 개발자들이 겪고 있는 흔한 문제입니다.
Background
이 문제의 근본적인 원인은 최근 출시된 Tailwind CSS v4의 대대적인 아키텍처 변경에 있습니다. v4부터는 제로 컨피그(Zero-config) 방식을 지향하여 더 이상 tailwind.config.js 파일이 필요하지 않게 되었습니다. 따라서 해당 파일을 생성하는 init 명령어 자체도 폐기(deprecated)되었습니다. 또한, 기존에는 메인 패키지에 포함되어 있던 CLI 도구와 PostCSS 플러그인이 별도의 패키지(@tailwindcss/cli, @tailwindcss/postcss)로 분리되었습니다. 현재 npm install tailwindcss를 실행하면 기본적으로 v4가 설치되기 때문에, 과거 v3 방식의 명령어를 사용하면 실행 파일을 찾을 수 없어 에러가 발생하는 것입니다.
Solution
이 문제를 해결하는 방법은 현재 진행 중인 프로젝트의 환경과 요구사항에 따라 세 가지로 나눌 수 있습니다.
1. Vite 환경에서 v4의 새로운 방식 적용하기 (권장)
가장 추천하는 방법은 v4의 새로운 플러그인 방식을 사용하는 것입니다. 더 이상 init 명령어나 tailwind.config.js 파일이 필요 없습니다.
# Tailwind CSS 코어와 Vite 전용 플러그인을 설치합니다.
npm install tailwindcss @tailwindcss/vite
// vite.config.js
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
// Vite 플러그인 배열에 tailwindcss를 추가합니다.
tailwindcss(),
],
})
/* src/index.css 또는 global.css */
/* 기존의 @tailwind 디렉티브 대신 @import를 사용합니다. */
@import "tailwindcss";
2. 프레임워크 없이 CLI로만 v4 사용하기
순수 HTML/JS 프로젝트이거나 커맨드라인에서 직접 빌드해야 한다면, 분리된 CLI 패키지를 추가로 설치해야 합니다.
# 코어 패키지와 CLI 패키지를 함께 설치합니다.
npm install tailwindcss @tailwindcss/cli
# v4부터는 명령어가 npx tailwindcss가 아닌 아래와 같이 변경되었습니다.
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch
3. 기존 v3 방식 유지하기 (레거시 호환)
만약 기존 프로젝트의 설정 파일(tailwind.config.js)을 그대로 사용해야 하거나, 아직 v4로 넘어갈 준비가 되지 않았다면 v3 버전을 명시하여 설치해야 합니다.
# @3 태그를 사용하여 v3 버전으로 명시적 설치를 진행합니다.
npm install -D tailwindcss@3
# 이제 기존처럼 init 명령어가 정상적으로 동작합니다.
npx tailwindcss init -p
Deep Dive
Tailwind CSS v4는 설정 파일이 사라진 대신 자동 소스 감지(Automatic Source Detection) 기능을 도입하여 프로젝트 내의 템플릿 파일들을 스스로 찾아냅니다. 기존 v3 프로젝트를 v4로 마이그레이션해야 한다면, 공식적으로 제공되는 업그레이드 도구(npx @tailwindcss/upgrade@next)를 사용하여 번거로운 작업의 대부분을 자동화할 수 있습니다. 주의할 점은 v4에서는 Sass, Less, Stylus 같은 CSS 전처리기에 대한 지원이 공식적으로 중단되었으며, .scss 파일 내에서 @import "tailwindcss";를 사용하는 것이 권장되지 않으므로 프로덕션 환경 적용 시 기존 스타일 파이프라인을 반드시 점검해야 합니다.
Conclusion
요약하자면, could not determine executable to run 에러는 Tailwind CSS가 v4로 메이저 업데이트되면서 기존의 init 명령어와 CLI 패키지 구조가 변경되었기 때문에 발생합니다. 새로운 프로젝트라면 v4의 간소화된 설정 방식(Vite 플러그인 또는 새로운 CLI)을 적극 도입하는 것을 권장하며, 기존 설정이 반드시 필요한 경우에만 v3 버전을 명시하여 설치하시기 바랍니다.