이 글은 Python UV 패키지 관리자 사용법에 대한 간결한 가이드입니다. pip으로 UV를 설치하고 uv init과 uv add를 사용한 프로젝트 관리, main.py 실행까지 초점을 맞추었습니다.
🚀 UV란?
UV는 Rust로 작성된 초고속 Python 패키지 관리자로, pip보다 최대 10-100배 빠르며 가상 환경 생성부터
패키지 관리, 스크립트 실행까지 한 도구에서 처리할 수 있습니다. pip, pip-tools, virtualenv, poetry 등을 대체할 수 있는 통합 솔루션입니다.
⚙️ 간단한 설치 방법
# pip으로 설치
pip install uv
# 설치 확인
uv --version설치가 성공하면 버전 정보가 다음과 같이 표시됩니다:
uv 0.1.23📁 프로젝트 시작하기 (uv init)
UV는 새 프로젝트를 쉽게 설정할 수 있는 init 명령어를 제공합니다:
# 기본 프로젝트 생성
uv init myproject
# Python 버전을 지정하여 프로젝트 생성
uv init myproject --python 3.11
# 특정 템플릿 사용
uv init myproject --template basic
# 해당 디렉토리로 이동
cd myproject이 명령은 다음을 수행합니다:
- 프로젝트 디렉토리 생성
- 지정한 Python 버전으로 가상 환경 자동 설정 (.venv)
- pyproject.toml 파일 생성 (Python 버전 정보 포함)
- main.py 파일 생성 (기본 코드 포함)
- 기본 프로젝트 구조 설정
생성된 main.py는 다음과 같은 기본 코드를 포함합니다:
def main():
print("Hello, world!")
if __name__ == "__main__":
main()📦 패키지 추가하기 (uv add)
uv add 명령으로 패키지를 설치하고 자동으로 의존성을 관리할 수 있습니다:
# 단일 패키지 추가
uv add requests
# 여러 패키지 한번에 추가
uv add numpy pandas matplotlib
# 개발 의존성으로 추가 (--dev)
uv add pytest --dev이 명령은 패키지를 설치하고 자동으로 pyproject.toml 파일을 업데이트합니다.
⚡ 코드 실행하기 (uv run)
UV는 가상 환경 활성화 없이도 스크립트를 바로 실행할 수 있는 run 명령어를 제공합니다:
# main.py 실행
uv run main.py
# 인수 전달
uv run main.py --argument value
# 특정 Python 모듈 실행
uv run -m pytest이 명령은 자동으로 프로젝트의 가상 환경을 사용하여 Python 스크립트를 실행합니다.
🔧 UV 주요 명령어
| 작업 | 명령어 | 설명 |
|---|---|---|
| 프로젝트 생성 | uv init myproject |
새 프로젝트 디렉토리와 가상 환경 생성 |
| 특정 Python 버전 지정 | uv init myproject --python 3.11 |
지정한 Python 버전으로 프로젝트 생성 |
| 패키지 추가 | uv add numpy |
패키지 설치 및 의존성 파일 업데이트 |
| 개발 의존성 추가 | uv add pytest --dev |
개발용 패키지 추가 |
| 의존성 설치 | uv sync |
pyproject.toml 기반으로 모든 의존성 설치 |
| 패키지 업데이트 | uv add --upgrade numpy |
특정 패키지 최신 버전으로 업데이트 |
| 스크립트 실행 | uv run main.py |
가상 환경 내에서 Python 스크립트 실행 |
🔄 pip 호환 명령어
UV는 기존 pip 명령어도 지원합니다:
# pip 스타일 설치 명령
uv pip install requests
# requirements.txt 사용
uv pip install -r requirements.txt💻 실용적인 예시
새 프로젝트 시작하기
# Python 3.11로 새 프로젝트 생성
uv init fastapi-app --python 3.11
cd fastapi-app
# 필요한 패키지 추가
uv add fastapi uvicorn
uv add pytest black --dev
# 의존성 설치 확인
uv pip list
# main.py 수정 후 실행
# main.py에 FastAPI 코드 작성
uv run main.py🚀 FastAPI 앱 개발 예시
# main.py 예시
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)# 위 코드가 작성된 main.py 실행
uv run main.py기존 프로젝트 복제하기
git clone https://github.com/user/project.git
cd project
# 의존성 설치
uv sync📝 스크립트 관리하기
UV는 pyproject.toml에서 스크립트를 정의하고 관리할 수 있습니다:
[project.scripts]
start = "myproject.main:main"
dev = "myproject.main:dev_server"정의된 스크립트 실행:
# start 스크립트 실행
uv run -m myproject.scripts start
# 또는 더 짧게
uv run start⚠️ 주의사항
- 새로운 도구이므로 일부 복잡한 프로젝트에서는 호환성 이슈가 있을 수 있음
- 중요한 프로덕션 환경에서는 테스트 후 도입 권장
📚 참고 자료
🌟 UV의 장점
- 🚀 속도: pip보다 훨씬 빠른 패키지 설치 및 의존성 해결
- 🧩 통합: 여러 도구 대신 하나의 도구로 모든 패키지 관리 가능
- 📦 현대적: pyproject.toml 기반의 의존성 관리 지원
- 🔄 호환성: 기존 pip 명령어와 호환되어 쉽게 전환 가능
- ⚡ 간편한 실행: 가상 환경 활성화 없이
uv run으로 스크립트 직접 실행 - 🔢 다중 버전: 다양한 Python 버전 관리 기능 제공