uv·uvx·npm·npx 차이: 프로젝트 실행과 일회성 도구 실행 구분

uv uvx npm npx 차이를 찾을 때 가장 먼저 볼 것은 네 도구가 겉모습이 비슷해도 정확한 일대일 대응 관계는 아니라는 점이다. Python과 Node.js의 package·environment 모델이 다르고, 각 command가 project dependency를 다루는지 executable을 실행하는지도 다르다.

먼저 네 command를 다음 질문으로 나누면 덜 헷갈린다.

1. 현재 project의 dependency와 environment를 다루는가
2. package가 제공하는 CLI를 격리된·임시 context에서 실행하는가

한눈에 보는 역할

command	주된 역할	대표 사용
uv	Python version·project·dependency·environment·tool을 아우르는 package manager	uv add, uv sync, uv run
uvx	uv tool run의 alias, Python CLI tool을 project와 격리해 실행	uvx ruff check .
npm	Node.js package dependency와 package script 관리	npm install, npm run build
npx	npm exec 기반으로 local 또는 fetched package executable 실행	npx eslint .

그러므로 uv ≈ npm, uvx ≈ npx는 기억을 돕는 비유일 뿐 동일한 semantic을 보장하지 않는다.

uv project에서는 add·sync·run을 연결한다

uv add는 dependency declaration과 lockfile을 갱신하고, uv sync는 project environment를 lockfile과 맞춘다. uv run은 command를 실행하기 전에 project environment가 최신인지 확인한다.

uv add "mcp[cli]"
uv sync --locked
uv run server.py

uv pip install은 pip-compatible interface가 필요한 경우에 쓸 수 있지만, uv 공식 문서는 uv-managed project environment를 직접 mutate하는 방식을 권장하지 않는다. project dependency라면 uv add와 uv sync를 우선한다.

uvx는 설치 없는 마법이 아니라 격리된 tool 실행이다

uvx는 정확히 uv tool run의 alias다. package의 dependency를 project와 분리된 environment에 준비하고, 그 package가 제공하는 executable을 실행한다. environment는 cache될 수 있지만 disposable하게 취급된다.

uvx ruff check .
uvx --from 'ruff==0.14.0' ruff check .

모든 Python library를 uvx package-name으로 실행할 수 있는 것은 아니다. package가 CLI entry point를 제공해야 한다. 재현성이 필요하면 검증한 version을 명시하고, lock된 project tool이어야 한다면 uv run을 사용한다.

npm install과 npm run은 project context를 사용한다

npm install은 package.json과 lockfile을 기준으로 dependency를 project에 추가하거나 설치한다. npm run <script>는 package.json의 scripts entry를 실행하며 local node_modules/.bin도 PATH에 포함한다.

{
  "scripts": {
    "build": "tsc",
    "start": "node build/index.js"
  }
}

CI에서 lockfile을 그대로 재현하려면 일반적으로 npm ci가 적합하다. runtime·platform·registry와 install script 같은 외부 조건까지 같아야 완전한 재현성을 기대할 수 있다.

npx는 npm exec의 interface다

현재 npx는 별도 standalone package가 아니라 npm exec를 사용한다. local dependency에 executable이 있으면 이를 사용할 수 있고, 없으면 registry package를 cache 영역에 받아 실행할 수 있다. 이때 install prompt가 나타날 수 있다.

npx eslint .
npx --package=typescript@5.9.3 -- tsc --version

자동화에서 prompt를 없애기 위해 --yes를 무조건 붙이는 것은 위험하다. package name typo나 dependency confusion이 곧 code 실행으로 이어질 수 있으므로 package와 version을 검증하고 lock된 project dependency를 우선한다.

목적별 선택표

상황	우선 선택	이유
Python project dependency 추가	uv add	declaration·lockfile·environment를 함께 관리
Python project command 실행	uv run	project environment를 사용
project와 무관한 Python CLI 1회 실행	uvx	isolated tool environment
Node project dependency 설치	npm install 또는 CI의 npm ci	manifest·lockfile 기반
Node project script 실행	npm run	package script와 local binary 사용
Node CLI를 임시 실행	npx/npm exec	package executable을 실행하되 신뢰 경계 확인

MCP 설정에서는 “Python이면 uvx, Node면 npx”처럼 언어만 보고 고르지 않는다. local source project라면 uv run, compiled artifact라면 node, published CLI package라면 검증된 uvx·npx가 후보가 된다. 실제 command와 args 조합은 Amazon Q Developer MCP 설정, server code는 Hello World MCP 구현으로 이어진다.

참고 자료

• uv: Running commands in projects
• uv: Tools
• npm Docs: Scripts
• npm Docs: npx