uv
uv - 파이선 관리에 필요한 단 하나의 툴
uv는 패키지 설치 및 관리와 패키지 빌드 및 배포까지 모두 가능한 궁극의 파이썬 종속성/패키지/프로젝트 관리 툴이다. 기존에 사용되던 pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv 등의 프로젝트, 패키지 관리 툴들을 모두 대체하는 궁극의 툴이다.
Rust로 만든 프로그램답게, 속도 또한 다른 툴들과 비교도 되지 않을 정도로 빠르다. 특히나 이미 다운로드한 패키지의 경우 기본 값으로 하드 링클르 이용해 설치하기 때문에 정말 정말 빠른데다 저장 공간도 추가로 필요하지 않다.
설치
설치는 다음과 같은 방식으로 진행할 수 있다.
# 맥OS, 리눅스, WSL
curl -LsSf https://astral.sh/uv/install.sh | sh
# 윈도우
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
pip install uv으로 설치할 수는 있지만 uv는 프로젝트 관리 툴이기에 특정 환경에 구애받게 설치되는 것보단 위의 방법을 이용해서 전역으로 설치하는 것을 추천한다.
설치 확인
설치가 제대로 됐는지 아래의 명령어로 uv 버전을 확인할 수 있다.
kimseoyeon:~/ $ uv --version [16:31:04]
uv 0.8.11 (Homebrew 2025-08-14)
버전 업데이트
독립형(standalone)으로 설치한 경우에만 아래의 명령으로 uv 버전을 업데이트 할 수 있다.
가상 환경 만들기
가상 환경을 만드는 명령어는 다음과 같다. python -m venv .venv에 대응하는 명령어이다.
uv venv .venv
이렇게 만들어진 가상 환경은 uv 전용이라던가 하는 것이 나닌, 그냥 pip, poetry에서도 상요할 수 있는 완전히 같은 가상 환경이다. 다만 속도는 venv로 만드는 것에 비해 비교하기 어려울 정도로 빠르다.
파이썬 환경 설정 및 자동 설치
-p <파이썬 버전> 인자를 추가해 파이썬 버전을 지정해 다운로드 할 수도 있다.
uv 명령어 구조
기본적인 사용법은 아래와 같다.
사용법: uv [옵션] <명령어>
명령어:
run 명령어나 스크립트 실행
init 새 프로젝트 생성
add 프로젝트에 의존성 추가
remove 프로젝트에서 의존성 제거
sync 프로젝트의 환경 업데이트
lock 프로젝트의 락파일 업데이트
export 프로젝트의 락파일을 다른 형식으로 내보내기
tree 프로젝트의 의존성 트리 표시
tool Python 패키지가 제공하는 명령어 실행 및 설치
python Python 버전 및 설치 관리
pip pip 호환 인터페이스로 Python 패키지 관리
venv 가상 환경 생성
build Python 패키지를 소스 배포판 및 휠로 빌드
publish 배포판을 인덱스에 업로드
cache uv의 캐시 관리
self uv 실행 파일 관리
version uv 버전 표시
help 명령어에 대한 문서 표시
주요 명령어
CLI Reference 페이지에서 모든 명령어의 옵션과 설명을 확인 할 수 있다.
- python
- run
- venv
- init
- add / remove
- sync / pip / export
- tree
uv 주요 기능
파이썬 설치: uv python
uv python 명령어를 통해서 원하는 버전의 파이썬을 한 번에 설치 가능하다.
uv python install 3.12 3.13
가상 환경에서 실행: uv run
uv run 명령어를 사용하여 설치되지 않은 파이썬 버전을 자동으로 설치하고, 필요한 패키지를 포함시켜 스크립트를 실행할 수 있다.
uv run --python 3.10 --with fastapi,pytest main.py
- python 3.10이 설치되어 있지 않다면 자동으로 다운로드하고 설치
- fastapi와 pytest 패키지를 설치
- main.py 파일을 실행
가상 환경: uv venv
uv venv로 가상 환경을 생성하고 관리한다. 특정 Python 버전을 사용하여 가상 환경을 생성할 수 있다. 설치되지 않은 파이썬 버전이면 자동으로 설치한다.
uv venv --python 3.10 .venv
uv로 프로젝트 관리
프로젝트 초기화: uv init
uv init 명령어는 프로젝트 구조를 자동으로 설정하고 필요한 기본 파일들을 생성해 준다.
uv init my-app --app --python 3.10
└── my-app
├── .venv
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock
--app: 애플리케이션용 프로젝트 생성--python <PYTHON>: 지원할 최소 파이썬 버전 지정
필요에 따라서 기존의 프로젝트에 pyproject.toml 파일만 추가해서 패키지를 설치하고 관리할 수도 있다.
uv init --bare
--bare: pyproject.toml 파일만 생성--script: 스크립트 생성--package: 파이썬 패키지로 프로젝트 설정--lib: 라이브러리용 프로젝트 생성
패키지 관리
uv add를 통해 원하는 패키지를 추가할 수 있다.
--extra <EXTRA>: 패키지의 선택적 의존성(extras)을 설치하는 데 사용--dev: 개발 의존성으로 추가--group <GROUP>: 특정 그룹으로 의존성 추가
uv add fastapi
uv add uvicorn --extra standard
uv add ruff --dev
uv add pytest --group test
# pyproject.toml
[project]
name = "my-fastapi-app"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
"fastapi>=0.116.1",
"uvicorn[standard]>=0.35.0",
]
[dependency-groups]
dev = [
"ruff>=0.12.9",
]
test = [
"pytest>=8.4.1",
]
의존성 패키지를 삭제할 때는 uv remove 명령어를 사용한다. add 와 유사한 옵션을 사용할 수 있다.
uv remove fastapi uvicorn
uv remove --dev
uv remove --group test
패키지 설치 및 동기화
pyproject.toml 파일이 있는 경우에는 uv sync를 사용 할 수 있다. 다양한 옵션으로 그룹을 지정하여 패키지를 설치 할 수 있다.
# 모든 의존성 설치 (기본값)
uv sync
# 개발 의존성을 제외하고 설치
uv sync --no-dev
# 개발 의존성만 설치
uv sync --only-dev
# 명시적으로 특정 의존성 포함하여 설치
uv sync --group test
또는 uv pip install를 통해 requirements.txt에서 패키지를 설치할 수 있다.
uv pip install -r requirements.txt
반대로 uv export 명령어를 통해 현재 설치된 패키지를 requirements.txt 파일로 만들수 있다.
uv export -o requirements.txt
의존성 시각화
uv tree로 프로젝트의 의존성 구조를 확인할 수 있다.
uv tree
my-app v0.1.0
└── fastapi v0.115.12
├── pydantic v2.11.3
│ ├── annotated-types v0.7.0
│ ├── pydantic-core v2.33.1
│ │ └── typing-extensions v4.13.1
│ ├── typing-extensions v4.13.1
│ └── typing-inspection v0.4.0
│ └── typing-extensions v4.13.1
├── starlette v0.46.1
│ └── anyio v4.9.0
│ ├── exceptiongroup v1.2.2
│ ├── idna v3.10
│ ├── sniffio v1.3.1
│ └── typing-extensions v4.13.1
└── typing-extensions v4.13.1
