이건 첫번째 레슨, uv 너만 갖기

제발 python이 주 언어인 개발자사람이면 uv 씁시다.

---

uv란?

uv란? Astral에서 Rust 기반으로 개발한 파이썬 패키지 매니져이다.

기존의 pip, poetry, virtualenv, anaconda 등을 대체 가능하며, python 버전 관리, python 프로젝트 관리, 의존성 관리 등에 유용하다!

• 공식 도큐먼트
• github

uv를 써야하는 이유

여러분의 시간은 소중하니까요.

uv 공식 도큐먼트에 따르면 pip보다 10~100배는 빠르다고 한다.
누구나 개발하다 보면 한번쯤은 가상환경에서 의존성 라이브러리 설치한다고 pip 엔터 해놓고 수 분 동안 멍 때린 경험이 있을 것이다.

그리고 의존성 꼬여서 다시 멍 때리다보면 시간이 훌쩍..

그리고 uv init 하면 자동으로 pyproject.toml를 제공하므로 버전 및 dependency 관리에도 용이하다.

---

간단한 uv 사용법

uv는 linux, mac, windows에서 모두 사용 가능하다. 명령어 한 줄로 간단하게 설치할 수 있다

Installation

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

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

uv command

물론 공식 도큐먼트나 깃허브를 참조하면 되지만 간단하게 주요 커맨드만 적어보겠다.

• 새 가상환경 생성

# 기본 가상환경
uv venv 

# 파이썬 버전 명시
uv venv --python 3.11

# 가상환경 이름 명시
uv venv myenv

# 시스템 사이트 패키지 접근 허용
uv venv --system-site-packages

생성된 가상환경은 venv와 같이 source ~/bin/activate로 활성화, deactivate로 비활성화 할 수 있다.

• 새 프로젝트 생성

# 현재 디렉토리에 프로젝트 초기화
uv init 

# 새 디렉토리에 프로젝트 생성
uv init my-awesome-project

# 특정 Python 버전으로 초기화
uv init --python 3.11 my-project

# 라이브러리 프로젝트 생성
uv init --lib my-library

• 패키지 설치

# 가상환경에 패키지 설치
uv pip install requests numpy pandas

# requirements.txt로 설치
uv pip install -r requirements.txt

# 개발 의존성 포함
uv pip install -e ".[dev]"

• 프로젝트 관리

# 기본 의존성 추가
uv add requests
uv add "fastapi>=0.68.0"
uv add numpy pandas matplotlib

# 개발 의존성 추가
uv add --dev pytest black ruff mypy

# 선택적 의존성 그룹 생성
uv add --optional web fastapi uvicorn
uv add --optional docs sphinx

# 특정 소스에서 설치
uv add --git https://github.com/user/repo.git package-name
uv add --path ./local-package
uv add --url https://files.pythonhosted.org/packages/.../package.whl

# 스크립트 실행
uv run python main.py

# 의존성 잠금
uv lock

# 기본 동기화 (lock 파일 기준)
uv sync

# 개발 의존성 포함 동기화
uv sync --dev

# 특정 그룹만 동기화
uv sync --group test
uv sync --group docs

# 모든 그룹 동기화
uv sync --all-groups

# 특정 의존성 제외
uv sync --no-dev

# 의존성 업데이트
uv lock --upgrade

# 의존성 제거
uv remove requests

# 개발 의존성 제거
uv remove --dev pytest

# 여러 패키지 동시 제거
uv remove numpy pandas matplotlib

• 버전 관리

#사용 가능한 Python 버전 확인
uv python list

# Python 설치
uv python install 3.11
uv python install 3.12.0
uv python install 3.11 3.12 3.13

# 설치된 Python 버전 확인
uv python list --only-installed

# 프로젝트에 Python 버전 고정
uv python pin 3.11
uv python pin 3.12.0

# Python 버전 제거
uv python uninstall 3.10

• 패키지 빌드(build) 및 배포(publish)

# wheel과 sdist 빌드
uv build

# wheel만 빌드
uv build --wheel

# sdist만 빌드  
uv build --sdist

# 특정 디렉토리에 빌드
uv build --out-dir dist/

# PyPI에 배포
uv publish

# Test PyPI에 배포
uv publish --repository testpypi

# 토큰으로 인증
uv publish --token $PYPI_TOKEN

# 사용자명/비밀번호로 인증
uv publish --username myuser --password mypass

---

비교적 최신 도구이지만 주요 프로젝트에서 점차 더 많이 uv를 채택할 것이라고 생각한다. 파이썬 기반 프로젝트를 개발하고 있고 개발환경 관리에 어려움을 느낀적이 있다면, uv를 한번 사용해보자!