Python uv 핵심 개념: pyproject.toml·잠금 파일·가상 환경
4 min read
명령어를 마구 치기 전에 이 4가지 개념을 머리에 넣으세요: "의존성은 어디에 쓰는지, 잠금 파일은 무엇을 위한 건지, venv는 언제 만들어지는지"가 명확해집니다. 게임하기 전에 스킬 설명을 읽는 것처럼 — 읽지 않으면 이유 없이 계속 죽습니다.
개념 1: pyproject.toml은 프로젝트의 신분증
프로젝트 메타데이터와 의존성 모두 여기에 씁니다. PEP 518 표준 형식입니다.
[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"requests>=2.31",
]- 수동 편집:
pyproject.toml직접 편집 - 명령어로 변경:
uv add requests·uv remove requests가 자동으로 업데이트
혼용하지 마세요 — 수동 또는 명령어, 하나로 통일. 둘 다 쓰면 충돌합니다.
개념 2: uv.lock은 의존성 스냅샷
pyproject.toml은 "무엇을 원하는지"를 씁니다 (예: requests>=2.31). uv.lock은 "실제로 설치된 버전"을 기록합니다 — 모든 전이 의존성까지 정확하게.
- 왜 잠금 파일이 필요한가? 모든 팀원·CI·프로덕션이 완전히 같은 의존성 트리를 설치하도록 보장합니다. "내 환경에서는 되는데 네 환경에서는 터진다"는 더 이상 없습니다.
- 커밋해야 하나? 예.
uv.lock은 버전 관리에 포함해서 팀과 CI가 같은 의존성 트리를 사용하게 하세요.
# 잠금 파일 업데이트 (예: 패키지 업그레이드)
uv lock --upgrade-package requests개념 3: .venv는 프로젝트 전용 샌드박스
uv는 프로젝트 루트에 .venv를 만듭니다 — uv add한 모든 패키지가 여기에 들어가고 시스템 Python과 격리됩니다.
- 수동으로 activate해야 하나? 아니요.
uv run이 자동으로 이 환경을 사용합니다. - 커밋해야 하나? 아니요.
.venv는.gitignore에 넣으세요.
# 환경 수동 동기화 (예: 새로 클론한 후)
uv sync
source .venv/bin/activate # 이후 python, pytest 등을 직접 사용 가능개념 4: uv run은 편리한 실행 진입점
uv run이 하는 일:
- 잠금 파일이 pyproject.toml과 일치하는지 확인
- .venv가 잠금 파일과 동기화되었는지 확인
- 올바른 환경에서 지정한 명령을 실행
uv run python main.py
uv run pytest
uv run flask run -p 3000activate를 기억할 필요도, 잘못된 환경을 걱정할 필요도 없음 — uv에게 맡기면 됩니다. 화장실 위치를 생각하지 않아도 자연스럽게 가는 고양이처럼. 이 "열면 바로 실행되는" 경험은 한 번 써보면 돌아갈 수 없습니다.
다음 단계
핵심 개념을 소화했다면 자주 쓰는 작업으로 이동: 의존성 관리·uvx·스크립트 실행. 👉 일반적인 패턴