UV ?

Rust로 개발한 초고속 파이썬 패키지 & 프로젝트 매니저

UV의 역할

UV는 파이썬 개발에 필요한 여러 도구를 하나로 합친 것

• pip 대체 : uv pip install fastapi → pip보다 10~100배 빠른 설치
• pip-tools 대체 : uv pip compile → requirements 락파일 생성
• virtualenv/venv 대체 : 프로젝트마다 자동 가상환경 관리 (uv run, uv add)
• pipx 대체 : uvx ruff check . → 설치 없이 툴 실행
• pyenv 대체 일부 : uv python install 3.12 → 파이썬 버전 설치/관리

즉, 파이썬 환경 세팅 + 패키지 관리 + 툴 실행 + 파이썬 버전 설치를 올인원으로 해결하는 툴

UV의 특징

속도

Rust로 구현돼서 pip 대비 훨씬 빠름
캐싱/병렬 설치 최적화 → 수십~수백 배 성능 향상 가능

호환성

uv pip … 인터페이스는 pip와 거의 동일해서 기존 습관 그대로 사용 가능.
requirements.txt 워크플로도 지원.

통합성

한 도구로 가상환경, 패키지, 툴, 파이썬 버전까지 관리 가능.
별도 pip, pipx, pyenv, poetry를 오가며 쓸 필요가 줄어듦.

자동 관리

uv run … 실행 시 자동으로 프로젝트 전용 venv 생성/사용.
사용자는 activate/deactivate 같은 걸 직접 안 해도 됨.

+ uv 와 uvicorn

uv = 패키지/환경/런타임 관리 도구
uvicorn = ASGI 서버 (FastAPI 실행할 때 쓰는 서버, 이름만 비슷)

---

설치

• macOS / Linux

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

• PowerShell(Windows)

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

• CMD(Windows)_스탠드얼론 설치

powershell -ExecutionPolicy Bypass -Command "iwr https://astral.sh/uv/install.ps1 -UseBasicParsing | iex"

• 추후 업그레이드 시

uv self update

또는

• CMD(Windows)_pipx 설치

python -m pip install --user pipx
python -m pipx ensurepath
pipx install uv

• 추후 업그레이드 시

pipx upgrade uv

설치 확인

uv --version

중요) pip install uv 로 설치하게 되면 설치되는 위치가 현재 실행 중인 파이썬 환경에 따라 달라짐

이 경우:

-다른 프로젝트에서 패키지 버전이 충돌할 수 있고,
-PATH 설정이 꼬이면 uv 명령이 안 잡히거나, 특정 가상환경 안에서 인식이 안 될 수도 있음

그래서 공식 문서도 pip install uv보다는
curl로 스탠드얼론 설치하거나 pipx install uv로 격리 설치를 추천
이렇게 하면 시스템 파이썬에 섞이지 않고, 항상 깨끗한 uv 실행 파일을 전역에서 쓸 수 있음.

---

프로젝트 초기화

uv init --app

현재 디렉토리에 pyproject.toml이 생김

---

fastapi 설치

uv add fastapi[standard]

+ uv add fastapi 와 uv pip install fastapi 의 차이

둘 다 패키지를 설치하지만, 쓰임새와 관리 방식이 다름.

* uv pip … (pip 대체 모드)

기존 pip를 빠르게 대체하는 모드
requirements.txt나 수동 패키지 설치에 익숙한 경우 그대로 사용 가능
가상환경 : 원하면 직접 python -m venv .venv 같은 걸 만들어야 함
=> 기존 pip 워크플로우와 100% 유사하게 쓰고 싶을 때

uv pip install fastapi
uv pip list
uv pip uninstall fastapi

* uv add … (프로젝트 모드)

pyproject.toml + uv.lock 기반의 프로젝트 단위 패키지 관리
pyproject.toml 파일을 수정하고, uv.lock을 자동 생성
프로젝트 의존성을 기록하고 재현성 보장
가상환경 : 프로젝트마다 자동으로 venv를 생성하고 관리함
=> 팀 단위 협업, CI/CD, 재현 가능한 환경을 원할 때

uv init --app             # 프로젝트 초기화 (pyproject.toml 생성)
uv add fastapi[standard]  # fastapi 추가 → toml/lock 자동 업데이트
uv run fastapi dev        # 프로젝트 실행 (자동 가상환경)

---

+ fastapi와 fastapi[standard] 차이점

-uv add fastapi 만 하면 필수 의존성만 설치 (uvicorn은 빠져있음)
-uv add fastapi[standard] 를 하면 uvicorn, python-dotenv 등 개발용에 필요한 라이브러리까지 같이 설치

---

main.py 실행

uv run fastapi dev main.py          # 배포 시 부적합

또는

uv run uvicorn main:app --reload    # 배포 시 사용 가능

+ uv run fastapi dev main.py 과 uv run uvicorn main:app --reload 차이

명령어	내부 동작	편의 기능	적합한 상황
uv run fastapi dev main.py	Uvicorn 실행 (자동 감지)	.env 로드, 파일 자동 검색, 개발용 기본 설정	개발 환경 (학습/실험)
uv run uvicorn main:app --reload	직접 Uvicorn 실행	없음 (옵션 직접 지정 필요)	개발/운영 모두 (더 명시적)