Python uv 빠른 시작: 첫 번째 프로젝트 만들기

이 가이드는 최단 경로로 동작하는 Python 프로젝트를 완성합니다 — uv에서의 첫 번째 사용 가능한 환경 구축. 작은 수달을 처음 키우는 것처럼: 먹고 자는 것부터 해결하고, 고급 기술은 나중에 배웁니다.

사전 조건

uv --version

버전 번호가 나오면 설치 완료. 없으면 설치 스크립트를 다시 실행하고 터미널을 재시작하세요.

uv init my-app
cd my-app

uv가 자동으로 pyproject.toml·.python-version·main.py·README.md를 만듭니다. 구조는 대략 이렇습니다:

my-app/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

uv run main.py

Hello from my-app!이 보이면 — 축하합니다, 첫 번째 프로젝트 탄생!

uv add requests

main.py를 수정해서 테스트:

import requests
r = requests.get("https://httpbin.org/get")
print(r.status_code)

실행:

uv run main.py

200이 보이면 의존성이 가상 환경에 올바르게 설치된 것 — 수동 pip install도, source .venv/bin/activate도 필요 없습니다. 이 "생각 없이 쓰는" 느낌이 uv의 즐거움입니다.

현상	확인 방향
`uv: command not found`	PATH 미설정 — 터미널 재시작 또는 인스톨러 출력에 따라 `source ...` 실행
`Permission denied`	설치 경로 권한 문제 — `~/.local/bin`이 쓰기 가능한지 확인
의존성 설치가 느림	첫 번째는 다운로드 필요, 이후는 캐시 사용; 네트워크 문제 시 프록시 확인

프로젝트가 실행되면 pyproject.toml과 uv.lock이 무엇을 하는지 이해하는 것을 권장합니다. 다음 글에서 이 핵심 개념들을 설명합니다: 👉 핵심 개념