바이브 코딩docs.astral.sh
uv로 파이썬 환경 만들기AI가 짜 준 코드를 내 컴퓨터에서 바로 돌리기
uv를 설치하고, Claude나 Cursor가 짜 준 파이썬 코드를 명령 한 줄로 실행하는 방법을 따라 해요.
안녕하세요, muaco입니다.
이 글로 할 수 있는 일
Claude나 Cursor에 부탁하면 파이썬 코드를 금방 짜 줘요. 그런데 막상 내 컴퓨터에서 돌리려고 하면 "파이썬을 먼저 까세요", "라이브러리를 설치하세요" 같은 말이 줄줄이 나와요. 이 글에서는 uv라는 도구 하나를 깔아서 이 준비를 한꺼번에 끝내요. 다 읽고 나면 AI가 준 코드를 파일로 저장하고 명령 한 줄로 실행할 수 있어요.
uv는 파이썬 코드를 돌리는 데 필요한 준비를 맡아 주는 관리 도구예요. 공식 문서는 uv를 "Rust로 만든 아주 빠른 파이썬 패키지·프로젝트 관리 도구"라고 소개해요. 예전에는 pip, virtualenv, pyenv처럼 여러 도구를 따로 써야 했던 일을 uv 하나가 대신해요. 문서에 따르면 pip보다 10~100배 빠르다고 해요.
미리 갖춰야 할 것
- 운영체제: Windows, macOS, Linux 모두 돼요. 공식 문서가 세 가지를 모두 지원한다고 밝혀요.
- 파이썬: 미리 깔지 않아도 돼요. 문서에 따르면 uv는 파이썬이 필요할 때 알아서 내려받아요. 이미 깔려 있어도 괜찮아요.
- 인터넷 연결: 설치할 때, 그리고 처음 실행할 때 파이썬과 라이브러리를 내려받아야 해요.
- 터미널: 글자로 명령을 쳐서 컴퓨터를 움직이는 창이에요. 식당에 비유하면 메뉴판 대신 주방에 직접 말로 주문하는 창구예요. Windows에서는 PowerShell, macOS에서는 "터미널" 앱을 써요.
계정이나 요금제는 필요 없어요. uv는 무료로 공개된 도구예요.
따라 하기: 설치부터 첫 실행까지
아래 순서는 2026년 9월 공식 문서를 기준으로 했어요. 모두 일곱 단계인데, 설치, 실행, 반복 실행 세 묶음으로 나눴어요.
uv 설치하기
- 터미널을 열어요. Windows는 시작 메뉴에서 "PowerShell"을 검색하고 macOS는 Spotlight에서 "터미널"을 검색해요. 깜빡이는 커서가 보이는 창이 뜨면 준비가 된 거예요.
- 내 운영체제에 맞는 설치 명령을 붙여 넣고 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를 써요. 인터넷에서 설치 파일을 받아 바로 실행하는 명령이라, 글자가 쭉 올라가다 멈추면 끝난 거예요. - 터미널을 닫았다가 새로 열고
uv라고 쳐요. 영어로 "An extremely fast Python package manager."로 시작하는 도움말이 보이면 설치가 잘 된 거예요. 공식 문서는 설치기가 셸 설정을 고친다고 밝혀 두었어요. 이미 열려 있던 창은 바뀐 설정을 아직 읽지 않았을 수 있어서 새로 여는 편이 안전해요.
여기서 다들 한 번 멈칫해요. Windows 명령에 들어 있는 ExecutionPolicy ByPass는 "이번 한 번만 인터넷에서 받은 설치 스크립트 실행을 허용한다"는 뜻이에요. 공식 주소(astral.sh)에서 받은 명령인지 꼭 확인하고 붙여 넣으세요.
AI가 짜 준 코드 실행하기
- AI가 준 코드를 메모장 같은 편집기에 붙여 넣고
hello.py처럼 끝이.py인 이름으로 저장해요. 파일 탐색기에서 아이콘 이름이hello.py로 보이면 돼요. Windows 메모장은 끝에.txt를 몰래 붙이기도 하니 "파일 형식"을 "모든 파일"로 바꿔서 저장해요. - 터미널에서
cd 폴더경로로 파일을 둔 폴더에 들어간 뒤uv run hello.py를 쳐요. 폴더 이름에 빈칸이 있으면cd "C:\Users\me\My Folder"처럼 경로 전체를 큰따옴표로 감싸요. 코드가 출력하는 글자가 화면에 뜨면 성공이에요. 컴퓨터에 파이썬이 없으면 이때 uv가 알아서 내려받아서 처음 한 번은 조금 오래 걸려요. - 코드가 외부 라이브러리를 쓴다면
uv run --with requests hello.py처럼--with뒤에 라이브러리 이름을 붙여요. 여러 개라면--with를 이름마다 한 번씩 반복해요. 오류 없이 결과가 나오면 필요한 부품이 제대로 들어간 거예요.
자주 돌릴 코드라면
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 한 줄이면 돼요.
이상으로 글 마치겠습니다.