02. uv

uv 란?

---

uv 란 pip, pyenv, virtualenv 등을 대체하기 위해 24년에 출시된 Python 패키지 매니저다. Rust 로 작성되어 pip 보다 10배에서 많게는 100배까지 빠른 성능을 보여준다.

uv 설치 (mac/linux)

---

brew install uv
uv --version

Python 설치

---

uv python install 3.13
uv python list

프로젝트 초기화

---

uv init
# or
uv init project-name

project-name/
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

프로젝트를 초기화하면 위와 같은 파일들이 생성된다.

.python-version

3.13

.python-version 파일은 해당 디렉토리(및 하위 디렉토리) 내에서 사용할 Python 런타임 버전을 고정하기 위한 메타데이터 파일이다. 원래 pyenv 가 인식하는 형식이지만 uv 역시 이를 감지하여 명시된 버전을 우선 시도한다. 내용은 매우 단순하며 보통 한 줄로 구성된다.

pyproject.toml

[project]
name = "python-study"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

pyproject.toml 은 Python 프로젝트의 메타데이터, 의존성, 빌드 백엔드 등을 선언하는 표준 파일이다. uv 는 이 파일을 단일 진실 소스로 사용하여 의존성 해석과 lock 생성(uv.lock)을 수행한다.

가상환경 생성

---

uv venv --python 3.13
source .venv/bin/activate

project-name/
├── .venv/
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

가상환경을 생성하면 .venv 가 생성된다. 가상환경을 생성하지 않고 uv add 를 사용해도 가상환경이 자동으로 생성된다.

패키지 관리

---

uv add pandas
uv remove pandas

project-name/
├── .venv/
├── .python-version
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock

uv add pandas 와 같이 실행하면 pyproject.toml 의 dependencies 섹션을 업데이트하고, 해결된 정확한 버전은 uv.lock 에 기록된다. uv.lock 은 재현 가능한(Repeatable) 설치를 위해 커밋하는 것이 권장된다.

Python 실행

---

uv run main.py

uv run 을 사용하면 굳이 가상환경을 활성화하지 않아도 된다.