💻 내가 보려고 작성한 UV 완벽 가이드

UV는 Rust로 구현된 초고속 Python 환경 관리 도구로, Python 개발 환경을 가장 빠르고 간단하며 강력하게 관리할 수 있습니다. 기존의 여러 도구들(pyenv, pip, pipenv, venv 등)을 하나로 통합했습니다.

(깃허브) https://github.com/astral-sh/uv/blob/main/README.md

이 가이드에서는 UV의 핵심 기능과 실무 적용 방법을 상세히 알아보겠습니다.

1. UV의 개념과 특징

https://docs.astral.sh/uv/getting-started/

UV란 무엇인가?

UV는 Astral에서 개발한 Rust 기반의 Python 환경 관리 도구로, Python 생태계에서 사용되는 다양한 도구들을 하나의 통합된 CLI로 제공합니다.

• 기존에 사용하던 pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv 등을 대체할 수 있습니다.

핵심 특징

https://docs.astral.sh/uv/

• 초고속 성능: Rust 언어로 작성되어 기존 도구보다 10~100배 빠른 속도 제공
• 통합된 워크플로우: Python 버전 관리부터 패키지 설치, 가상환경 생성, 프로젝트 배포까지 일관된 인터페이스 제공
• 디스크 공간 최적화: 하드 링크를 활용해 중복 패키지 설치 방지
• 재현 가능한 빌드: 정확한 의존성 잠금과 해결 메커니즘
• 모던한 패키지 관리: pyproject.toml을 표준으로 사용하여 PEP 621 준수

2. UV 설치 방법

https://docs.astral.sh/uv/getting-started/installation/#standalone-installer

운영체제별 설치 가이드

Windows

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

macOS/Linux

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

PyPI를 통한 설치

pip install uv

설치 확인

uv --version

💡 참고: UV를 전역으로 설치하는 것을 권장합니다. pip install uv로 설치할 경우 특정 환경에 종속되기 때문에, 위의 스크립트를 통한 설치 방법이 더 효과적입니다.

3. UV 핵심 기능 상세 가이드

Python 설치하기

최신 파이썬 설치하기:

uv python install

특정 버전 파이썬 설치하기:

uv python install 3.12

(복수개) 특정 버전 파이썬 설치하기:

uv python install 3.11 3.12

설치 시 에러, 또는 다시 설치가 필요한 경우

uv python install --reinstall

Python 버전 관리

UV를 사용하면 기존 pyenv와 유사하게 다양한 Python 버전을 설치하고 관리할 수 있습니다.

명령어	설명
uv python install <버전>	지정한 Python 버전 설치 (uv python install 3.12)
uv python list	설치 가능한 Python 버전 목록 표시 (uv python list )
uv use <버전>	현재 디렉토리에 .python-version 파일 생성하여 기본 Python 버전 지정 (uv use 3.11)

💡 고급 기능: uv python install --with-patches <패치명> <버전>과 같이 특정 패치가 적용된 Python 버전을 설치할 수도 있습니다.

Python 설치 시, UV는 python-build-standalone 프로젝트를 사용하여 필요한 최소한의 구성요소만 다운로드합니다.

• 이는 빠른 설치를 가능하게 하지만, IDLE이나 기타 표준 도구가 포함되지 않을 수 있습니다.

프로젝트 초기화 및 구성

UV는 프로젝트 초기화를 위한 간단한 명령어를 제공합니다.

명령어	설명	생성되는 파일/디렉토리
uv init	기본 프로젝트 초기화	pyproject.toml, .python-version
uv init --package	패키지 형태 프로젝트 생성	pyproject.toml, .python-version, src/ 디렉토리
uv init --lib	배포용 라이브러리 프로젝트 생성	라이브러리 구조의 pyproject.toml, 테스트 디렉토리 등

💼 pyproject.toml 예시:

[project]
name = "my-project"
version = "0.1.0"
description = "A sample Python project"
requires-python = ">=3.8"
dependencies = []

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

💡 참고: uv init 명령어는 .venv 가상환경을 즉시 생성하지 않습니다.

• 하지만 이후 uv add, uv run, uv sync 등의 명령어를 실행하면 자동으로 생성됩니다.

가상환경 생성 및 관리

UV는 가상환경을 효율적으로 생성하고 관리하는 기능을 제공합니다.

명령어	설명	사용 상황
uv venv [경로]	(프로젝트와 별개로 빠르게 가상환경 필요 시) 가상환경 생성
uv venv -p 3.11 [경로]	(시스템 Python과 다른 버전으로 작업 필요 시) 특정 Python 버전으로 가상환경 생성
uv sync	(프로젝트 클론 후 환경 재현 시) pyproject.toml과 uv.lock 기반으로 .venv 동기화

💼 venv 예시:

# 특정 Python 버전으로 가상환경 생성
uv venv -p 3.10 .venv-310

# 현재 프로젝트 설정으로 가상환경 동기화
uv sync

현재 프로젝트 설정으로 가상환경 동기화란?

• uv sync 명령어의 의미는 단순히 "현재 경로의 .venv와 동기화한다"는 의미가 아니라, 현재 프로젝트 디렉토리에 존재하는 pyproject.toml 및 uv.lock 파일을 기준으로 가상환경을 구성(재현)한다는 의미입니다.

• 즉, 이런 흐름이 됩니다:

  1. uv init 혹은 수동으로 pyproject.toml 작성
  2. 의존성 추가 → uv add ...
  3. uv lock 실행 → uv.lock 생성됨
  4. 이후에:
     • .venv가 존재하지 않거나 or 새로운 환경을 만들었을 경우
       → uv sync는 pyproject.toml과 uv.lock을 기준으로 필요한 패키지를 .venv (혹은 다른 지정된 가상환경) 에 설치하여 환경을 일관성 있게 재현하는 작업을 수행합니다.

💡 성능 이점: UV로 생성한 가상환경은 표준 venv 모듈로 생성한 것과 호환되지만, 생성 속도가 훨씬 빠릅니다.

참고 : UV venv와 UV init의 차이점

uv venv와 uv init은 목적과 사용 시나리오가 다릅니다:

uv venv

• 목적: 순수하게 가상환경만 생성
• 결과물: Python 인터프리터와 기본 패키지를 포함한 가상환경(.venv 디렉토리)
• 사용 시기: 빠르게 격리된 Python 환경이 필요할 때, 프로젝트 설정 없이 단순 실험할 때
• 특징: 프로젝트 파일(pyproject.toml) 생성하지 않음

uv init

• 목적: 프로젝트 초기화 및 구조 설정
• 결과물: pyproject.toml, .python-version 및 기타 프로젝트 파일
• 사용 시기: 새 Python 프로젝트를 시작할 때, 의존성 관리가 필요한 체계적인 개발 시
• 특징: 즉시 가상환경을 생성하지 않지만, 추후 명령어(uv sync, uv add 등) 실행 시 자동으로 생성

참고: 가상환경 활성화 방법

UV의 큰 장점 중 하나는 전통적인 가상환경 활성화(activate) 과정이 필요 없다는 점입니다.

• 하지만 다음과 같은 방법으로 사용할 수 있습니다:

1. UV 명령어로 직접 실행 (활성화 불필요)

uv run python script.py
uv add requests
uv run -- python -c "import sys; print(sys.prefix)"

2. 전통적인 가상환경 활성화 방법

Windows

.\.venv\Scripts\Activate.ps1
.\.venv\Scripts\activate.bat

macOS/Linux

source .venv/bin/activate

3. 가상환경 Python 직접 참조

Windows

.\.venv\Scripts\python script.py

macOS/Linux

./.venv/bin/python script.py

의존성 관리

UV는 의존성 추가, 제거, 업데이트를 효율적으로 관리합니다.

명령어	설명	예시
uv add <패키지>	의존성 추가	uv add requests
uv add --dev <패키지>	개발용 의존성 추가	uv add --dev pytest black
uv remove <패키지>	의존성 제거	uv remove requests
uv lock	락파일 생성/갱신	uv lock

💼 의존성 버전 지정 예시:

# 특정 버전 설치
uv add "requests==2.31.0"

# 버전 범위 설치
uv add "numpy>=1.24.0,<2.0.0"

💡 하드 링크의 이점: UV는 패키지 설치 시 하드 링크를 활용하여 동일한 패키지가 여러 환경에 설치되더라도 디스크 공간을 절약합니다.

• 하드 링크(Hard link)는 동일한 파일 데이터를 여러 위치에서 공유하도록 하는 파일 시스템 기능입니다.
• UV는 이미 설치된 패키지의 바이너리 파일을 복사하지 않고, 다른 가상환경에서 해당 파일에 대한 하드 링크만 생성하여 연결합니다.
• 이 방식은 여러 가상환경이 동일한 패키지를 사용하는 경우에도 디스크 공간을 추가로 소모하지 않으며, 설치 속도도 비약적으로 향상됩니다.
  • 예를 들어 numpy와 같은 대형 패키지를 여러 프로젝트에서 사용하더라도 실제 디스크에는 하나만 존재하며, 각 .venv는 해당 파일에 대한 참조만 가지게 됩니다.

실행 및 스크립트 관리

UV를 사용하여 가상환경 내에서 명령어와 스크립트를 실행할 수 있습니다.

명령어	설명	예시
uv run <명령어>	가상환경에서 명령어 실행	uv run python script.py
uv run --with <패키지> <명령어>	추가 패키지와 함께 실행	uv run --with rich script.py
uv pip freeze	설치된 패키지 목록 출력	uv pip freeze > requirements.txt

💼 예시 - 자주 사용하는 명령어:

# Jupyter Lab 실행
uv run jupyter lab

# 테스트 실행
uv run pytest

💡 자동 가상환경 생성: .venv가 없는 상태에서 uv run을 실행하면, UV는 자동으로 가상환경을 생성하고 의존성을 설치합니다.

도구 관리 (uvx와 uv tool)

UV는 Python 기반 CLI 도구를 효율적으로 관리하는 두 가지 방법을 제공합니다.

uv tool - 영구 설치

명령어	설명	예시
uv tool install <도구>	CLI 도구 영구 설치	uv tool install black
uv tool uninstall <도구>	설치된 도구 제거	uv tool uninstall black
uv tool list	설치된 도구 목록 표시	uv tool list

uvx - 일회성 실행

uvx는 CLI 도구를 임시 환경에서 실행하는 명령어로, uv tool run의 별칭입니다.

명령어	설명	예시
uvx <도구> [인자]	도구 임시 설치 및 실행	uvx black .
uvx --from '<패키지>' <명령어>	특정 패키지 버전으로 실행	uvx --from 'ruff==0.3.0' ruff check .

💡 성능 최적화: uvx는 캐싱 메커니즘을 사용하여 같은 도구를 반복 실행할 때 성능을 최적화합니다.

UV - 기능별 명령어 요약

앞에서 소개한 내용들과 UV의 주요 기능별 명령어를 정리해보았습니다.

Python 버전 관리

• uv python install: Python 버전 설치
• uv python list: 설치 가능한 버전 목록 표시
• uv python find: 현재 시스템에서 설치된 Python 탐색
• uv python pin: 현재 프로젝트에 특정 버전 고정
• uv python uninstall: 설치된 버전 제거

스크립트 실행

• uv run: 스크립트 실행 (가상환경 자동 적용)
• uv add --script: 스크립트 전용 의존성 추가
• uv remove --script: 스크립트 의존성 제거

프로젝트 관리

• uv init: 프로젝트 초기화 (pyproject.toml 생성)
• uv add: 프로젝트 의존성 추가
• uv remove: 프로젝트 의존성 제거
• uv sync: 환경 동기화 (uv.lock 기반)
• uv lock: 락파일 생성 및 업데이트
• uv run: 프로젝트 환경 내 명령어 실행
• uv tree: 의존성 트리 시각화
• uv build: 프로젝트 빌드
• uv publish: 패키지 배포

도구 실행 및 관리

• uvx 또는 uv tool run: 임시 환경에서 도구 실행
• uv tool install: 사용자 전역 도구 설치
• uv tool uninstall: 전역 도구 제거
• uv tool list: 설치된 도구 목록
• uv tool update-shell: PATH 반영 등 쉘 업데이트

패키지 및 환경 관리 (pip 호환 레벨)

• uv venv: 가상환경 생성 (venv 대체)
• uv pip install: 패키지 설치
• uv pip uninstall: 패키지 제거
• uv pip freeze: 패키지 목록 출력 (버전 포함)
• uv pip show: 설치된 패키지 상세 정보
• uv pip check: 패키지 호환성 검사
• uv pip list: 설치된 패키지 나열
• uv pip tree: 의존성 트리 확인

고급 환경 관리 (pip-tools 호환 레벨)

• uv pip compile: requirements.txt에서 락파일 생성
• uv pip sync: 락파일 기반 환경 구성 동기화

각각의 명령어는 독립적으로 사용할 수도 있으며, 조합하여 완전한 Python 개발 파이프라인을 구축할 수 있습니다.

4. 실무 적용 워크플로우

데이터 사이언스 프로젝트 템플릿

# 1. 프로젝트 디렉토리 생성
mkdir ds-project
cd ds-project

# 2. 프로젝트 초기화 및 Python 버전 설정
uv init --package
uv python install 3.11
uv use 3.11

# 3. 데이터 사이언스 핵심 패키지 설치
uv add numpy pandas matplotlib scikit-learn

# 4. 개발 도구 설치
uv add --dev ipython jupyterlab black ruff

# 5. 환경 잠금 및 동기화
uv lock
uv sync

# 6. Jupyter Lab 실행
uv run jupyter lab

이 템플릿을 사용하면 일관된 데이터 사이언스 환경을 쉽게 구축할 수 있습니다.

웹 개발 프로젝트 템플릿

# 1. 프로젝트 생성
mkdir web-project
cd web-project

# 2. 프로젝트 초기화
uv init --package
uv python install 3.12
uv use 3.12

# 3. 웹 프레임워크 및 관련 패키지 설치
uv add "fastapi>=0.104.0" "uvicorn[standard]" sqlalchemy pydantic

# 4. 개발 도구 설치
uv add --dev pytest pytest-cov black ruff

# 5. 환경 잠금 및 동기화
uv lock
uv sync

# 6. 개발 서버 실행
uv run uvicorn src.main:app --reload

기존 프로젝트 마이그레이션

기존의 requirements.txt 또는 Pipfile 기반 프로젝트를 UV로 마이그레이션하는 방법:

# 1. 프로젝트 디렉토리로 이동
cd existing-project

# 2. UV 프로젝트 초기화
uv init

# 3. requirements.txt가 있는 경우 의존성 가져오기
cat requirements.txt | xargs uv add

# 4. 환경 잠금 및 동기화
uv lock
uv sync

💡 팀 협업 팁: uv.lock 파일을 버전 관리 시스템에 포함하여 모든 팀원이 동일한 환경을 사용할 수 있도록 합니다.

5. UV vs 기존 도구 비교

기능	기존 도구	UV	UV의 장점
Python 설치	pyenv install 3.11	uv python install 3.11	빠른 설치, 자동 환경 설정
가상환경 생성	python -m venv .venv	uv venv .venv	10배 이상 빠른 속도
패키지 설치	pip install requests	uv add requests	의존성 자동 관리, 하드 링크 활용
의존성 고정	pip freeze > requirements.txt	uv lock	정확한 의존성 해결, 플랫폼별 최적화
환경 동기화	pip install -r requirements.txt	uv sync	빠른 설치, 확실한 재현성
도구 실행	pipx run black .	uvx black .	캐싱 활용, 빠른 실행

성능 비교

다음은 동일한 환경에서 각 도구의 성능을 비교한 예시입니다:

작업	기존 도구	UV	속도 향상
가상환경 생성	2-3초	0.2-0.3초	~10배
pandas 설치	15-20초	2-3초	~7배
프로젝트 환경 동기화	30-60초	3-6초	~10배

6. 고급 사용법 및 팁

커스텀 인덱스 사용

특정 패키지 인덱스(PyPI 외의 소스)를 사용하는 방법:

# 특정 인덱스에서 패키지 설치
uv pip install --index-url https://my-custom-index.org/simple some-package

# pyproject.toml에 인덱스 추가
# [tool.uv]
# index-url = "https://my-custom-index.org/simple"

빌드 및 배포

UV를 사용하여 패키지를 빌드하고 배포하는 방법:

# 패키지 빌드
uv build

# PyPI에 배포
uv publish

환경 내보내기 및 가져오기

다른 도구와의 호환성을 위한 환경 내보내기:

# requirements.txt로 내보내기
uv pip freeze > requirements.txt

# Poetry 형식으로 내보내기
uv export -f poetry > pyproject.toml

디버깅 및 문제 해결

UV 사용 시 발생할 수 있는 문제를 해결하는 팁:

# 자세한 로그 출력
uv --verbose add requests

# 캐시 정리
uv cache clean

# 의존성 트리 확인
uv pip show --tree pandas

7. 실무 적용 사례

대규모 ML 프로젝트

대규모 머신러닝 프로젝트에서 UV를 사용한 경우, 의존성 해결 및 환경 설정 시간이 기존 대비 85% 감소했습니다. 특히 GPU 드라이버와 호환되는 정확한 패키지 버전을 빠르게 설치할 수 있어 생산성이 크게 향상되었습니다.

CI/CD 파이프라인

CI/CD 파이프라인에서 UV를 활용한 경우, 빌드 시간이 평균 72% 단축되었습니다. 하드 링크를 활용한 디스크 공간 최적화로 클라우드 환경에서의 리소스 활용도 개선되었습니다.

마이크로서비스 개발

여러 마이크로서비스로 구성된 프로젝트에서 UV를 통해 일관된 환경을 유지하면서도 각 서비스별 의존성을 효율적으로 관리할 수 있었습니다. 특히 uvx를 통한 도구 실행으로 개발자 간 일관된 코드 품질을 유지할 수 있었습니다.

8. 결론

UV는 Python 개발 환경 관리를 위한 새로운 표준을 제시합니다. Rust 기반의 뛰어난 성능과 직관적인 인터페이스를 통해 기존 도구들의 복잡성을 해소하고, 프로젝트 생성부터 배포까지 일관된 워크플로우를 제공합니다.

🌈 주요 장점:

• 단일 도구: 여러 도구를 대체하는 통합된 인터페이스
• 속도: 기존 도구 대비 10배 이상 빠른 성능
• 공간 효율성: 하드 링크를 통한 디스크 공간 최적화
• 재현성: 정확한 의존성 해결과 잠금 기능
• 현대적: PEP 621 기반의 pyproject.toml 지원

UV를 사용함으로써 Python 개발자는 환경 설정에 소요되는 시간을 줄이고, 실제 개발에 더 집중할 수 있습니다. 빠르고 간결한 환경 관리를 통해 더 나은 Python 개발 경험을 제공하는 UV로의 전환을 고려해보세요!!

읽어주셔서 감사합니다 😎