Python, 패키지/가상환경 관리 도구 UV

[참조]https://sigridjin.medium.com/파이썬-개발자라면-uv-를-사용

Python, 패키지/가상환경 관리 도구 UV

 

UV는 Rust 언어로 만들어져서 속도가 빠르며 다음 기능을 지원한다.

 

엄청나게 빠른 의존성 해석 엔진 제공

가상환경 자동 생성/관리

의존성 관리

파이썬 버전 관리

패키징 관리

다양한 서드파티 도구 실행

 

uv CLI 명령으로 대부분의 작업을 수행할 수 있음

 

프로젝트 만들기

uv init uv-demo
cd uv-demo

• uv init 명령으로 새 프로젝트 초기화 (uv-demo 폴더명은 변경 가능)
• 프로젝트 폴더 내부 구조는 다음과 같음

uv-demo/
├── .python-version
├── .gitignore
├── pyproject.toml
├── hello.py
└── README.md

• .python-version : 파이썬 버전 고정
• pyproject.toml : 의존성 및 프로젝트 메타데이터 정의 파일
• .venv 폴더는 의존성을 추가하면 자동 생성됨

 

requirements.txt 파일을 이용한 의존성 설치 비교

kuzu==0.7.1
lancedb==0.17.0
llama-index==0.12.8
llama-index-llms-openai==0.3.12
llama-index-embeddings-openai==0.3.1
llama-index-graph-stores-kuzu==0.6.0
llama-index-vector-stores-lancedb==0.3.0
numpy==2.2.1
polars==1.18.0
pyarrow==18.1.0
python-dotenv==1.0.1

# 사전 준비: 캐시 정리
`uv clean cache`
`pip cache purge`
`poetry cache clear - all .`

 

pip 사용 예

python -m venv .venv      # 로컬 가상환경 생성
source .venv/bin/activate # 가상환경 활성화
time pip install -r requirements.txt

 

poetry 사용 예

rm -rf .venv             # 기존 가상환경 제거
poetry init              # poetry 설정 초기화
poetry shell             # poetry가 만든 가상환경 진입
time poetry install      # 의존성 설치

• poetry는 `poetry.lock`을 생성하고, 이를 기반으로 의존성을 세심하게 관리합니다.

 

uv 사용 예

uv init                           # pyproject.toml 생성(필요 시)
time uv add -r requirements.txt   # 의존성 설치

• .venv 폴더가 자동 생성되고, 가상환경을 활성화할 필요 없음
•  `uv run` 명령으로 Python 파일을 실행할 때, .venv 환경이 자동 적용됨.
• pip나 poetry에 비해 3~10배 빠름

 

VS Code, Cursor ID

• .venv 가상 환경을 IDE가 인식하게 해줌
• uv add -- dev ipykernel 명령을 통해 개발용 의존성(dev dependency group)으로 설치하면, IDE가 자동 감지하여 가상환경 커널을 연결

uv add -r requirements.txt  # 주요 의존성 설치
uv add --dev ipykernel      # 개발용(인터랙티브) 의존성 추가

• 팀원이 다른 에디터를 이용할 때, uv sync 하면 같은 .venv 이용 가능

 

UV 명령

1. uv run

• Python 스크립트를 CLI에서 실행할 때, uv가 가상환경을 적용해줌

# hello.py 예시
import polars as pl

df = pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
print("Hello from uv-demo!")
# 명령줄에서
uv run hello.py
# 출력: Hello from uv-demo!

 

- Python 설치 확인 및 자동 설치

- .venv 가상환경 생성 및 활성화

- pyproject.toml 기반 의존성 설치

- 지정한 소스 파일을 실행함

 

이 과정을 uv run 한 줄로 처리함.

 

2. uv sync

• CI/CD 등 자동화 환경에서 uv sync로 프로젝트용 Python 버전과 .venv를 자동 동기화

3. 의존성 잠금파일(uv.lock)

•  `uv.lock` 파일을 생성해 의존성 버전을 고정시킴

 

----------------------------------------------------------------------------------------

uv init

• 새로운 uv 프로젝트 초기화하고 pyproject.toml 생성

uv add <패키지명>

• 특정 패키지 추가
• uv add -r requirements.txt로 `requirements.txt` 전체 패키지 설치 가능

uv sync

• pyproject.toml과 uv.lock 파일 기준으로 가상환경 재생성 및 동기화

uv run <파일명.py>

• 가상환경을 자동 적용하여 파이썬 스크립트 실행

uvx <툴> (`uv tool run` 명령 축약형)

• ruff, mypy 등 서드파티 명령을 자동 설치하고 실행함
• 예) uvx ruff check .

 

`uvx`로 ruff 사용하기

• Python 프로젝트에서 black, isort, flake8를 따로 설치하고 관리했지만, uv는 uvx ruff 명령어로 linter+formatter 역할을 ruff가 대신함

uvx ruff check .
uvx ruff format *.py --line-length 100

• uv와 ruff를 함께 쓰면, 코드 스타일 관리가 편리해짐

 

uv로 대체하는 것들

• pip:
• pyenv
• poetry
• venv
• pipenv