uv로 빠르고 재현 가능한 Python 프로젝트 세팅하는 법

Claude Code나 Codex 같은 AI 코딩 에이전트를 Python 프로젝트에 투입할 때, 마찰의 절반은 모델과 전혀 상관이 없다. 그 마찰은 환경에서 온다. 누락된 패키지, 잘못된 Python 버전, 에이전트가 활성화하는 것을 잊은 virtualenv, 또는 "제 컴퓨터에서는 됩니다"라고 말하는 동료. 해결책은 기본적으로 재현 가능한 프로젝트이며, 오늘날 그런 프로젝트를 가장 빠르게 만드는 방법은 Astral이 만든 Rust 기반 Python 툴체인 uv다.

uv는 pip, venv, pip-tools, pyenv를 빠른 단일 명령으로 대체하며, 잠금 파일(lockfile)을 작성해 정확히 동일한 의존성 트리가 어디서든 설치되도록 한다. 이 가이드는 아무것도 없는 상태에서 몇 분 만에 잠겨 있고 실행 가능한 프로젝트를 만드는 과정을 안내한다.

환경이 에이전트에게 중요한 이유

AI 에이전트는 사용자의 셸에서 명령을 실행하고 돌아오는 오류를 읽는다. 프로젝트에 선언된 의존성도, 고정된 Python 버전도 없으면 에이전트는 추측할 수밖에 없다. 잘못된 추측은 에이전트를 패키지를 전역으로 설치하거나 잘못된 인터프리터를 편집하는 토끼굴로 빠뜨린다. pyproject.toml과 uv.lock이 있는 프로젝트는 에이전트에게 단일한 진실의 원천을 제공한다. 에이전트는 uv sync를 실행해 올바른 패키지를 받고 다음 작업으로 넘어갈 수 있다. 그러면 검토 시간을 환경 고고학이 아니라 로직에 쓸 수 있다.

uv 설치하기

macOS 또는 Linux에서:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows(PowerShell)에서:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv는 자체 완결적인 단일 바이너리이므로, 그 밖에 따로 설정할 것이 없다.

명령어 하나로 프로젝트 시작하기

uv init weather-cli
cd weather-cli

이 명령은 동작하는 프로젝트를 스캐폴딩한다. 메타데이터와 의존성을 담는 pyproject.toml, .python-version 파일, 시작용 main.py, README.md, 그리고 .gitignore가 생성된다. virtualenv를 손으로 만들거나 활성화할 필요가 없다 — uv가 필요한 순간에 .venv를 알아서 관리한다.

의존성 추가하기 (그리고 잠금 파일이 중요한 이유)

uv add requests

이 명령은 세 가지를 한 번에 한다. requests를 pyproject.toml에 기록하고, 전체 의존성 트리를 해결하며, 정확하고 플랫폼 간 호환되는 고정 버전과 함께 uv.lock을 작성한다. 추가 시점에 버전을 고정할 수도 있다:

uv add 'requests==2.31.0'

uv.lock을 Git에 커밋하라. 이것이 "최신 requests 설치"(시간이 지나면서 달라진다)와 "우리가 테스트한 정확한 트리 설치"의 차이를 만든다. 에이전트가 — 또는 CI나 새 동료가 — uv sync를 실행하면 바이트 단위로 동일한 환경을 얻는다.

아무것도 활성화하지 않고 코드 실행하기

uv run main.py

uv run은 환경이 동기화되어 있는지 확인한 다음 그 안에서 실행한다 — source .venv/bin/activate 같은 절차가 필요 없다. 이는 특히 에이전트에게 중요하다. 각 도구 호출이 종종 새 셸에서 이뤄지기 때문에 "활성화 후 실행" 방식은 자주 깨지는 반면, 단일 uv run은 언제나 동작한다. 어떤 명령이든 감쌀 수 있다:

uv run -- pytest -q
uv run -- flask run -p 3000

에이전트와 CI가 일치하도록 Python 버전 고정하기

uv python pin 3.12

이 명령은 버전을 .python-version에 기록하며, uv는 해당 인터프리터를 자동으로 내려받아 사용한다 — 시스템 Python이 필요 없다. 이제 개발에 사용하는 버전이 에이전트, 동료, CI가 모두 사용하는 버전이 된다.

짧은 실전 예시

에이전트에게 "오늘의 날씨를 가져오는 명령을 추가해줘"라고 요청한다고 하자. uv가 갖춰져 있으면 전체 루프가 깔끔하다:

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# 에이전트가 main.py를 편집해 API를 호출한다...
uv run main.py

에이전트는 어떤 인터프리터가 활성화되어 있는지, requests가 설치되어 있는지 따질 필요가 전혀 없다 — 그 사실들은 에이전트가 읽을 수 있는 파일에 선언되어 있다. 새 의존성을 도입하면 uv add를 실행하고 잠금 파일이 갱신된다. CI에서 무언가 깨지면 uv sync가 정확한 환경을 로컬에서 재현해 디버깅할 수 있게 해준다.

uv가 향하는 방향

uv와 그 형제 도구인 ruff(린터/포매터), ty(타입 체커)는 널리 채택되고 있다 — uv 하나만 해도 월 1억 회를 훌쩍 넘는 다운로드를 기록한다. 2026년 3월, OpenAI는 이들을 만든 회사 Astral을 인수하기로 합의했으며, MIT 라이선스 도구들을 오픈 소스로 유지하기로 약속하면서 해당 툴체인을 자사의 Codex 플랫폼에 통합할 계획이다 (OpenAI, Simon Willison). 당장의 실용적인 교훈은 바뀌지 않는다. uv는 AI 에이전트가 추측 없이 그 위에서 작업할 수 있는 Python 프로젝트로 가는 가장 빠른 길이다.

빠른 참조

작업	명령어
프로젝트 생성	uv init <name>
의존성 추가	uv add <package>
Python 버전 고정	uv python pin 3.12
코드 실행	uv run <file or command>
환경 재현	uv sync
잠금 파일 업데이트	uv lock --upgrade-package <pkg>