비개발자의 Unity 개발 세팅 오류 해결 기록
Unity에서 AI 자동화를 붙여보겠다고 mcp-for-unity를 설치한 뒤, 아무 생각 없이 Start Server를 눌렀습니다.
[참조:unity-mcp-setup]
그리고 바로 첫 번째 벽을 만났습니다.
바로 uvx 내부 또는 외부 명령 어쩌고 에러.
'uvx'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다.
※ 영어 Windows 환경에서는 아래와 같은 메시지로 표시됩니다.
'uvx' is not recognized as an internal or external command,
operable program or batch file.
또한 MCP Setup 창에는 UV Package Manager가 빨간불로 표시되었습니다.
그 순간 깨달았습니다.
개발은 코드보다 세팅이 더 어렵다는 사실을.
1. 첫 번째 에러: ‘uvx’ 명령을 찾을 수 없음 (How to fix ‘uvx is not recognized’ in Unity)
이 에러의 핵심은 단순합니다.
Unity가 uvx라는 명령어를 실행하려 했지만,
Windows PATH에서 해당 실행 파일을 찾지 못한 상태입니다.
즉, 설치가 안 되었거나, 설치되었어도 Unity가 인식하지 못하는 상황입니다.
2. uvx 내부 또는 외부 명령 오류 해결법_uv 설치 방법 (Windows 기준)
✔ 방법 1: winget 사용
PowerShell을 열고 아래 명령을 실행합니다.
(↓ 아래 코드 블록을 한 번 클릭하면 자동으로 복사됩니다)
winget install -e --id astral-sh.uv
설치 후 반드시 확인합니다.
where.exe uv
uv --version
uv --version이 정상 출력되면 설치 성공where.exe uv가 경로를 출력하면 PATH 인식 성공
※ PowerShell에서는 where 대신 반드시 where.exe를 사용해야 합니다.
✔ 방법 2: winget이 작동하지 않을 때
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
설치 후 동일하게 버전 확인을 합니다.
3. uvx 내부 또는 외부 명령 오류 해결법_uvx.cmd 파일 생성 (Unity가 uvx를 찾게 만들기)
uv가 설치되어 있어도 uvx 명령이 없는 경우가 있습니다.
이 경우 직접 만들어 줍니다.
Step 1. 다음 경로로 uv라는 새 폴더 생성
C:\Tools\uv\
Step 2. uvx.cmd 파일 만들기
메모장을 열고 아래 내용을 입력합니다.
@echo off
uv tool run %*
파일을 다음과 같이 저장합니다.
- 파일명:
uvx.cmd - 위치:
C:\Tools\uv\
⚠ 파일 확장자가 .cmd인지 반드시 확인합니다.uvx.cmd.txt이면 작동하지 않습니다.
Step 3. 시스템 PATH에 추가
- Windows 검색 → “환경 변수”
- “시스템 환경 변수 편집” 클릭
- “환경 변수” 버튼 클릭
- “시스템 변수”에서
Path선택 → 편집 - 새로 만들기 →
C:\Tools\uv\추가
4. uvx 내부 또는 외부 명령 오류 해결법_가장 중요한 단계: Unity 완전 종료
여기서 대부분 막힙니다.
저도 ‘왜 안되지?’를 10번은 한 것 같습니다.
Unity는 환경변수를 실행 시점에 읽습니다.
이미 켜져 있던 Unity는 새 PATH를 모릅니다.
따라서 반드시 아래 순서로 진행합니다.
- Unity Editor 종료
- Unity Hub 종료
- 작업 관리자에서 Unity Hub 프로세스까지 종료(중요!)
- 다시 Unity Hub 실행
- 프로젝트 열기
그 후 MCP Setup에서 Refresh를 누르면 UV가 정상 인식됩니다.
결국 문제의 절반은 재시작이었습니다.
5. 두 번째 에러: No ‘git’ executable was found
uv 문제가 해결된 뒤 또 다른 에러가 등장했습니다.
No 'git' executable was found
mcp-for-unity는 Git 기반 패키지를 사용합니다.
Git이 설치되지 않으면 Unity는 패키지를 추가하거나 업데이트할 수 없습니다.
✔ Git 설치 방법
이번 사례에서는 Git도 PowerShell에서 직접 설치했습니다. uv와 동일하게 winget 명령을 사용하면 가장 간단합니다. 다음을 powershell에 복사 붙여넣기 합니다.
winget install -e --id Git.Git
설치 후 역시나 이것도 반드시 Unity와 Hub를 완전 종료 후 재실행합니다.
6. 비개발자가 배운 것
- 개발 세팅의 상당수는 환경변수 문제입니다
- 설치보다 재시작이 더 중요할 수 있습니다
- Unity는 환경변수 변경을 자동 반영하지 않습니다
- Git은 거의 기본 전제 조건입니다
코드를 한 줄도 작성하지 않았지만, 개발자의 고통을 일부 이해하게 되었습니다.
정확히는 코드가 아니라 PATH와 싸운 시간이었습니다.
7. 최종 체크리스트
아래 순서대로 하나씩 확인하면 대부분 해결됩니다.
- PowerShell에서
winget install -e --id astral-sh.uv실행 완료 uv --version명령으로 uv 정상 설치 확인where.exe uv로 실행 경로 확인C:\Tools\uv\폴더 생성 완료- 폴더 안에 메모장으로
uvx.cmd파일 생성 (@echo off+uv tool run %*입력) - 파일 확장자가
.cmd인지 확인 (.cmd.txt아님) - 시스템 환경 변수 Path에
C:\Tools\uv\추가 완료 - Git 미설치 시
winget install -e --id Git.Git실행 git --version으로 Git 정상 설치 확인- Unity Editor 종료
- Unity Hub 종료
- 작업 관리자에서 Unity 관련 프로세스 모두 종료
- Unity Hub 재실행 후 프로젝트 다시 열기
- MCP Setup에서 Refresh 클릭
- UV / Git 상태 초록불 확인
이 체크리스트를 순서대로 진행하면 대부분의 “uvx 내부 또는 외부 명령을 찾을 수 없습니다” 오류는 해결됩니다.
개발자분들에게는 아주 쉬운 내용이겠지만 저와 같은 비개발자한테는 하나 하나가 교통 체증이었습니다.
혹시나 같은 에러를 만난 분들이 검색으로 들어와 시간을 덜 낭비하기를 바라며 기록합니다.
→ 비개발자의 바이브코딩 과정과 앱 만드는 방법을 보고 싶다면? [바이브코딩으로 게임 만들기: 비개발자의 Google AI Studio 실험기 – Lifetestlab]
→ 앱 기획의 첫 걸음인 Axure로 Prototype 기획안을 만드는 방법을 보고 싶다면? [Axure RP Prototyping Tutorial: Popup Window & Basic Setup]
* 본 글은 개인적인 사용 경험과 데이터 분석을 바탕으로 작성되었으며, 개개인의 상태와 환경에 따라 체감은 달라질 수 있습니다.