Python 프로젝트 관리 도구, uv 설치 및 사용 가이드

 Python 프로젝트 관리를 혁신하는 도구, uv 설치 및 사용 가이드

---

 소개

Python 생태계에는 다양한 가상환경 및 의존성 관리 도구가 존재합니다. requirements.txt나 Anaconda, Poetry 등도 많이 쓰이지만, 최근 Rust 기반으로 개발되어 속도와 표준화를 모두 잡은 새로운 툴이 등장했으니, 바로 uv입니다. 이 글에서는 uv의 개요부터 설치 방법, 주요 사용 명령, 그리고 실제 예제까지 정리합니다.

---

1. uv란?

• Rust로 구현된 초고속 Python 패키지 및 프로젝트 매니저

• PEP 517, 518, 508, 660 등 PEP 표준 완전 지원

• 가상환경 생성, 의존성 설치/잠금, 빌드/배포까지 All-in-one 제공

uv를 쓰면 기존 도구보다 빠른 속도로 환경을 구성하고, 표준 기반 빌드 시스템을 통해 안정적인 패키지 관리를 경험할 수 있습니다.

---

2. 설치 방법

아래 중 편리한 방법을 골라 따라 해보세요.

# macOS & Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# pip
pip install uv

# pipx
pipx install uv

# Homebrew
brew install uv

# Arch Linux (Pacman)
pacman -S uv

위 명령들은 모두 공식 설치 스크립트 또는 패키지 매니저를 통해 uv를 시스템에 추가합니다.

---

3. 기본 사용법

3.1 Python 버전 관리

# 최신 배포된 CPython 3.10, 3.11 설치
uv python install 3.10 3.11 3.12

• 설치된 버전 확인:

uv python list

• <download available> 태그가 붙은 항목은 아직 설치되지 않은 버전을 의미합니다.

3.2 가상환경 생성

# 기본 가상환경 생성
uv venv

# 특정 파이썬 버전 지정
uv venv --python 3.12.0

• 생성된 가상환경 경로: .venv

• 활성화: source .venv/bin/activate

3.3 단일 명령 실행

# 프로젝트 없이, 즉시 원하는 버전 콘솔 실행
uv run --no-project --python pypy@3.8 -- python

• 해당 버전이 설치되어 있지 않으면 자동 설치 후 실행됩니다.

3.4 프로젝트 초기화 및 관리

# 새 프로젝트 생성 (pyproject.toml 작성)
uv init

# dependencies 추가
uv add <패키지명>

# dev dependencies 추가
uv add --dev <패키지명>

# 설치된 의존성 동기화
uv sync

# 잠금 파일 생성
uv lock

# 환경 내 명령 실행
uv run <명령>

# 의존성 트리 확인
uv tree

# 배포용 빌드
uv build

# PyPI 등으로 게시
uv publish

---

4. 실전 예제: FastAPI 프로젝트

1. 프로젝트 초기화

   uv init --no-workspace --python 3.12
   

   └ pyproject.toml, uv.lock 등 파일 자동 생성

2. 의존성 추가

   uv add fastapi --extra standard      # fastapi + 표준 extras
   uv add --dev ruff                    # 개발용 linter
   

   pyproject.toml 의 [project] 및 [dependency-groups] 섹션에 반영됩니다.

3. 코드 작성: main.py

   from fastapi import FastAPI
   
   app = FastAPI()
   
   @app.get("/")
   async def root():
       return {"message": "Hello World"}
   

4. 서버 실행

   uv run fastapi dev main.py
   

   • 개발용 모드에서 FastAPI 앱을 자동 감지·재실행하여 빠른 개발 경험 제공

---

5. 편리 팁: PyCharm 연동

• uv가 생성한 .venv를 PyCharm Interpreter로 지정

• uv sync 명령으로 pyproject.toml과 가상환경을 싱크하여, IDE 내 인덱싱 문제 해결

---

마치며

uv는 Rust의 속도와 PEP 표준 지원을 결합하여, Python 프로젝트 관리에 새로운 기준을 제시합니다. 가볍고 빠른 설치부터, 완전한 pyproject.toml 기반 워크플로우까지, 이제 여러분의 다음 프로젝트에서 uv를 꼭 활용해보세요!

Happy Coding! 🎉