muaco Tech Note

바이브 코딩docs.astral.sh

uv로 파이썬 환경 만들기AI가 짜 준 코드를 내 컴퓨터에서 바로 돌리기

uv를 설치하고, Claude나 Cursor가 짜 준 파이썬 코드를 명령 한 줄로 실행하는 방법을 따라 해 봅니다.

안녕하세요, muaco입니다.

이 글로 할 수 있는 일

uv 하나만 깔면 AI가 짜 준 파이썬 코드를 명령 한 줄로 실행할 수 있습니다. Claude나 Cursor에 부탁하면 코드 자체는 금방 나옵니다. 문제는 내 컴퓨터에서 돌릴 때입니다.

"파이썬을 먼저 까세요", "라이브러리를 설치하세요" 같은 안내가 줄줄이 따라붙습니다. 이 글에서는 uv라는 도구 하나로 이 준비를 한꺼번에 끝냅니다. 다 읽고 나면 AI가 준 코드를 파일로 저장해 바로 돌릴 수 있습니다.

uv는 파이썬 코드를 돌리는 데 필요한 준비를 맡아 주는 관리 도구입니다. 공식 문서의 소개는 "Rust로 만든 아주 빠른 파이썬 패키지·프로젝트 관리 도구". 예전에는 pip, virtualenv, pyenv를 따로 써야 했지만, 이제는 uv 하나가 그 일을 대신합니다.

속도는 어느 정도일까요? 문서에 따르면 pip보다 10~100배 빠릅니다.

미리 갖춰 둘 준비물

  • 운영체제: Windows, macOS, Linux 모두 됩니다. 공식 문서도 세 가지를 모두 지원한다고 밝히고 있습니다.
  • 파이썬: 미리 깔지 않아도 됩니다. 문서에 따르면 uv는 파이썬이 필요할 때 알아서 내려받습니다. 이미 깔려 있어도 문제없습니다.
  • 인터넷 연결: 설치할 때와 처음 실행할 때 파이썬과 라이브러리를 내려받아야 합니다.
  • 터미널: 글자로 명령을 쳐서 컴퓨터를 움직이는 창입니다. 식당에 비유하면 메뉴판 대신 주방에 직접 말로 주문하는 창구. Windows에서는 PowerShell을, macOS에서는 "터미널" 앱을 쓰면 됩니다.

따로 계정이나 요금제는 필요하지 않습니다. uv는 무료로 공개된 도구입니다.

따라 하기: 설치부터 첫 실행까지

아래 순서의 기준은 2026년 9월 공식 문서입니다. 모두 일곱 단계로, 설치와 실행, 반복 실행의 세 묶음으로 나눴습니다.

uv 설치하기

따라 하기
  1. 먼저 터미널을 여세요. Windows는 시작 메뉴에서 "PowerShell"을, macOS는 Spotlight에서 "터미널"을 검색합니다. 깜빡이는 커서가 보이는 창이 뜨면 준비 완료.
  2. 내 운영체제에 맞는 설치 명령을 붙여 넣고 Enter를 누르세요. Windows는 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"를 씁니다. macOS와 Linux라면 curl -LsSf https://astral.sh/uv/install.sh | sh를 쓰면 됩니다. 인터넷에서 설치 파일을 받아 바로 실행하는 명령이라, 글자가 쭉 올라가다 멈추면 설치가 끝납니다.
  3. 터미널을 닫았다가 새로 열고 uv라고 쳐 보세요. 영어로 "An extremely fast Python package manager."로 시작하는 도움말이 보이면 설치 성공입니다. 왜 새로 열어야 할까요? 공식 문서는 설치기가 셸 설정을 고친다고 밝혀 두었습니다. 이미 열려 있던 창은 바뀐 설정을 아직 읽지 않았을 수 있어서, 새로 여는 편이 안전합니다.

여기서 많은 분이 한 번 멈칫합니다. Windows 명령에 들어 있는 ExecutionPolicy ByPass는 "이번 한 번만 인터넷에서 받은 설치 스크립트 실행을 허용한다"는 뜻입니다. 붙여 넣기 전에 공식 주소(astral.sh)에서 받은 명령인지 꼭 확인하세요.

AI가 짜 준 코드 실행하기

따라 하기
  1. AI가 준 코드를 메모장 같은 편집기에 붙여 넣으세요. 저장할 때는 hello.py처럼 끝이 .py인 이름을 씁니다. 파일 탐색기에서 아이콘 이름이 hello.py로 보이면 됩니다. Windows 메모장은 끝에 .txt를 몰래 붙이기도 합니다. 이를 막으려면 "파일 형식"을 "모든 파일"로 바꿔서 저장하세요.
  2. 터미널에서 cd 폴더경로로 파일을 둔 폴더에 들어간 뒤 uv run hello.py를 칩니다. 폴더 이름에 빈칸이 있다면 cd "C:\Users\me\My Folder"처럼 경로 전체를 큰따옴표로 감싸세요. 코드가 출력하는 글자가 화면에 뜨면 성공입니다. 컴퓨터에 파이썬이 없으면 이때 uv가 알아서 내려받습니다. 처음 한 번이 조금 오래 걸리는 이유입니다.
  3. 코드가 외부 라이브러리를 쓴다면 uv run --with requests hello.py처럼 --with 뒤에 라이브러리 이름을 붙입니다. 여러 개라면 이름마다 --with를 한 번씩 반복하세요. 오류 없이 결과가 나오면 필요한 부품이 제대로 들어간 상태입니다.

자주 돌릴 코드라면

따라 하기
  1. uv add --script hello.py requests를 한 번 쳐 두세요. 파일 맨 위에 # /// script로 시작하는 목록이 생기고, 그 안에 "requests"가 적히면 완료. 그다음부터는 --with 없이 uv run hello.py만 쳐도 됩니다. uv가 이 목록을 보고 부품을 챙기기 때문입니다.

7단계에서 파일 맨 위에 적히는 목록은 다음과 같습니다.

# /// script
# dependencies = [
#   "requests",
# ]
# ///

코드 파일에 장보기 목록을 붙여 둔다고 생각하면 쉽습니다. 파일을 동료에게 보내도 목록이 함께 갑니다. 받는 사람도 uv run 한 줄로 똑같이 돌릴 수 있습니다.

막히기 쉬운 세 군데

uv를 쳤는데 "찾을 수 없다"고 나옵니다

보이는 모습: macOS에서는 command not found: uv가 뜹니다. Windows에서는 uv라는 용어를 인식하지 못한다는 빨간 오류 문구가 나타납니다(정확한 문구는 PowerShell 버전에 따라 조금씩 다릅니다).

왜 그런지: 공식 문서의 제거 안내를 보면 uv 파일은 macOS·Linux에서는 ~/.local/bin/, Windows에서는 $HOME\.local\bin\에 놓입니다. 설치기는 터미널이 그 폴더를 찾아보도록 셸 설정을 고칩니다. 다만 이미 열려 있던 터미널은 바뀐 설정을 아직 읽지 않았을 수 있습니다.

어떻게 하는지: 우선 터미널을 모두 닫고 새로 여세요. 그래도 안 되면 위 폴더에 uv 파일이 실제로 있는지 파일 탐색기나 Finder로 확인합니다. 파일이 없다면 설치 명령을 다시 실행하면 됩니다.

ModuleNotFoundError가 뜹니다

보이는 모습: ModuleNotFoundError: No module named 'requests'처럼 어떤 이름의 모듈이 없다는 오류가 납니다.

왜 그런지: 코드는 외부 라이브러리를 쓰는데, uv에 그 라이브러리를 챙기라고 알려 주지 않은 상황입니다. uv는 --with나 파일 맨 위 목록으로 요청받은 부품을 준비합니다.

어떻게 하는지: 오류 메시지의 따옴표 안 이름을 --with 뒤에 붙여 다시 실행해 보세요. 자주 쓸 파일이라면 7단계처럼 uv add --script로 목록에 적어 둡니다.

가끔은 불러오는 이름과 설치할 때 쓰는 이름이 다른 라이브러리도 있습니다. 그럴 때는 AI에게 "이 오류를 해결하려면 어떤 패키지를 설치해야 해?"라고 물어보면 됩니다.

AI가 알려 준 python 명령이 안 먹힙니다

보이는 모습: AI는 python hello.py로 실행하라고 했는데, 파이썬을 찾을 수 없다는 오류가 납니다.

왜 그런지: 문서에 따르면 uv는 파이썬을 받아도 기본으로는 python3.13처럼 버전 번호가 붙은 이름만 설치합니다. 그래서 그냥 python이라고 치면 찾지 못할 수 있습니다.

어떻게 하는지: 앞부분 python을 uv run으로 바꿔 uv run hello.py를 치세요. 특정 버전이 필요하다면 uv run --python 3.12 hello.py처럼 버전을 적어 줍니다. 없는 버전이면 uv가 내려받습니다.

여기서 더 나아가려면

파일이 여러 개로 늘어나면 uv init으로 프로젝트를 만들어 관리할 수 있습니다. 프로젝트 폴더 안에서 파일을 돌리되 현재 프로젝트 설치는 건너뛰고 싶다면 어떻게 할까요? uv run --no-project hello.py를 쓰면 됩니다.

파일 맨 위에 7단계의 목록이 있다면 이 옵션은 없어도 됩니다. 이때는 uv가 프로젝트를 무시하고 목록대로 돌립니다. uv 자체를 새 버전으로 올릴 때는 uv self update 한 줄이면 충분합니다.

이상으로 글 마치겠습니다.

출처

#uv#파이썬#환경 설정#바이브 코딩#설치 가이드#Claude#Cursor

같은 분류의 글