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

원본 게시글: https://velog.io/@euisuk-chung/UV-내가-참고하려고-작성한-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 준수

1. UV 설치 방법

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

운영체제별 설치 가이드

Windows

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

macOS/Linux

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

PyPI를 통한 설치

1
pip install uv

설치 확인

1
uv --version

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

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

Python 설치하기

최신 파이썬 설치하기:

1
uv python install

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

1
uv python install 3.12

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

1
uv python install 3.11 3.12

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

1
uv python install --reinstall

Python 버전 관리

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

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

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

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

프로젝트 초기화 및 구성

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

💼 pyproject.toml 예시:

1
2
3
4
5
6
7
8
9
10
[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는 가상환경을 효율적으로 생성하고 관리하는 기능을 제공합니다.

💼 venv 예시:

1
2
3
4
5
# 특정 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 명령어로 직접 실행 (활성화 불필요)

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

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

Windows

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

macOS/Linux

1
source .venv/bin/activate

3. 가상환경 Python 직접 참조

Windows

1
.\.venv\Scripts\python script.py

macOS/Linux

1
./.venv/bin/python script.py

의존성 관리

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

💼 의존성 버전 지정 예시:

1
2
3
4
5
# 특정 버전 설치
uv add "requests==2.31.0"

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

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

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

실행 및 스크립트 관리

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

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

1
2
3
4
5
# Jupyter Lab 실행
uv run jupyter lab

# 테스트 실행
uv run pytest

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

도구 관리 (uvx와 uv tool)

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

uv tool - 영구 설치

uvx - 일회성 실행

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

💡 성능 최적화: 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 개발 파이프라인을 구축할 수 있습니다.

1. 실무 적용 워크플로우

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 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
2
3
4
5
6
7
8
9
10
11
12
# 1. 프로젝트 디렉토리로 이동
cd existing-project

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

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

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

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

1. UV vs 기존 도구 비교

성능 비교

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

1. 고급 사용법 및 팁

커스텀 인덱스 사용

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

1
2
3
4
5
6
# 특정 인덱스에서 패키지 설치
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를 사용하여 패키지를 빌드하고 배포하는 방법:

1
2
3
4
5
# 패키지 빌드
uv build

# PyPI에 배포
uv publish

환경 내보내기 및 가져오기

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

1
2
3
4
5
# requirements.txt로 내보내기
uv pip freeze > requirements.txt

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

디버깅 및 문제 해결

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

1
2
3
4
5
6
7
8
# 자세한 로그 출력
uv --verbose add requests

# 캐시 정리
uv cache clean

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

1. 실무 적용 사례

대규모 ML 프로젝트

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

CI/CD 파이프라인

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

마이크로서비스 개발

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

1. 결론

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

🌈 주요 장점:

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

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

읽어주셔서 감사합니다 😎

• Previous
  내가 보려고 정리한 터미널 함수 25선
• Next
  [개념] API에 대해서 이해해보자!