uv - 새로운 Python 패키지, 프로젝트 및 환경 매니저

Python uv의 장점

Page content

Python uv (발음: “유비”)는 Rust로 작성된 현대적이고 고성능의 Python 패키지와 프로젝트 매니저입니다. pip, pip-tools, virtualenv, pipx, pyenv와 같은 기존 Python 패키지 관리 도구의 대체재로 설계되었으며, Python 개발 워크플로우를 단순화하고 가속화하는 것을 목표로 합니다.

uv는 인기 있는 Python 린터인 Ruff를 개발한 팀인 Astral에서 개발했습니다. Rust의 성능과 현대적인 소프트웨어 아키텍처를 활용하여 Python 생태계의 공통적인 문제점들, 즉 느린 설치 속도, 의존성 충돌, 복잡한 환경 관리 등을 해결하도록 설계되었습니다.

uv python 초보 가이드

uv의 주요 특징

  • 탁월한 속도: uv는 기존 도구보다 훨씬 빠릅니다. 캐싱을 사용하지 않을 때 pip보다 일반적으로 810배 빠르고, 따뜻한(warm) 캐시를 사용할 경우 최대 80115배까지 빨라질 수 있습니다.
  • 올인원 도구: 단일 도구에서 패키지 설치, 의존성 해결, 가상 환경 관리, Python 버전 관리, 프로젝트 스캐폴딩(초기 구조 생성), 스크립트 실행 기능을 모두 제공합니다.
  • 호환성: pip와 호환되는 명령줄 인터페이스를 제공하므로, 가파른 학습 곡선 없이 쉽게 채택할 수 있습니다.
  • 강력한 의존성 관리: 재현 가능한 환경을 위한 정밀한 의존성 해결과 락파일(lockfile) 지원을 제공합니다.
  • 자동 가상 환경: 가상 환경을 자동으로 생성하고 관리하여 수동 설정 과정을 줄여줍니다.
  • 크로스 플랫폼 지원: macOS, Linux, Windows에서 모두 동작합니다.
  • 독립 설치: Python이나 Rust가 설치되어 있지 않아도 간단한 설치 프로그램이나 curl을 사용하여 설치할 수 있습니다.

uv vs poetry vs pdm vs pip 성능 비교

그래도 uv를 사용해야 하는 이유가 확신이 안 선다면?

  • 성능: 패키지 설치와 의존성 해결 시간을 현저히 줄여줍니다.
  • 단순성: 여러 도구를 하나로 통합하여 프로젝트 설정과 관리를 간소화합니다.
  • 신뢰성: 명확한 에러 메시지와 충돌 해결 기능을 통해 일관되고 재현 가능한 환경을 제공합니다.
  • 모던 스탠다드: 프로젝트 구성을 위해 pyproject.toml을 지원하여 최신 Python 패킹 표준과 부합합니다.

예시 사용 사례

흥미로운 것들을 시도해 보겠습니다!

  • 새로운 프로젝트 시작:
uv init myproject
cd myproject
uv add requests
uv run python script.py

이 과정은 프로젝트 디렉터리를 생성하고, 가상 환경을 설정하며, 의존성을 설치한 후, 격리된 환경에서 스크립트를 실행합니다.

  • 인라인 의존성을 가진 스크립트 관리:
uv add --script script.py requests
uv run script.py

uv는 별도의 요구사항(requirements) 파일 없이 단일 파일 스크립트의 의존성을 관리할 수 있습니다.

기존 도구와의 비교

기능 uv pip/virtualenv Poetry
속도 매우 빠름 느림 보통
가상 환경 자동 수동 자동
의존성 해결 고급 기본 고급
Python 버전 관리 있음 없음 (pyenv 필요) 없음
락파일 지원 있음 없음 (pip-tools 필요) 있음
스크립트 실행 통합 지원 없음 제한적

내 시스템에 UV를 설치하고 사용하기 시작하는 방법

시스템에 uv를 설치하고 사용하기 시작하려면 다음 간단한 단계를 따르세요:

설치

  1. 독립 설치 프로그램 (권장)
    • Linux/macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh

또는 wget를 선호하신다면:

wget -qO- https://astral.sh/uv/install.sh | sh
  • Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • 특정 버전: URL에 버전을 포함시켜 특정 버전을 요청할 수 있습니다. 예: https://astral.sh/uv/0.7.15/install.sh.
  1. 대안: pip를 통해 설치 (Python이 설치되어 있는 경우)
pip install uv

참고: 이 방법은 시스템 전체에서 접근하려면 권장되지 않습니다. 왜냐하면 시스템 Python 환경을 지저분하게 만들 수 있기 때문입니다(본인이 그 결과를 충분히 이해하고 있을 때만 사용하세요).

  1. pipx를 통해 설치 (격리된, 사용자 전체용 설치)
pipx install uv

이미 pipx를 사용하고 있다면 전역 접근을 위해 이 방법이 더 깔끔합니다.

시작하기

설치 확인을 위해 다음을 실행하세요:

uv

uv가 설치되어 준비된 상태임을 확인하는 도움말 메뉴가 표시됩니다.

가상 환경 생성 및 활성화

  • venv 생성:
uv venv test
  • Linux/macOS에서 활성화:
source test/bin/activate
  • Windows에서 활성화:
.\test\Scripts\activate

이제 이 환경에서 uv pip install 을 사용하여 패키지를 설치할 수 있습니다.

새로운 프로젝트 초기화

uv init

이 명령은 프로젝트의 pyproject.toml과 .gitignore를 생성합니다.

의존성 추가

패키지 추가:

uv add

이 명령은 pyproject.toml을 업데이트하고 락 파일을 생성하거나 업데이트합니다.

의존성 동기화

환경의 모든 의존성을 설치합니다:

uv sync

또는 pip와 호환되는 인터페이스를 사용하세요:

uv pip install

이것은 락 파일에 따라 모든 의존성이 설치되었음을 보장합니다.

스크립트 실행

사용 방법:

uv run script.py

이 명령은 스크립트에 대한 환경과 의존성을 자동으로 관리합니다.

셸 통합 (선택 사항)

더 원활한 워크플로우를 위해, 기본 가상 환경을 자동으로 활성화하고 pip를 uv pip로 별칭을 지정하도록 .zshrc나 .bashrc에 셸 통합을 추가할 수 있습니다.

이 단계를 통해 uv가 설치되고, 속도와 편의성을 바탕으로 Python 프로젝트를 관리할 준비가 갖춰집니다.

특정 Python 버전 설치

uv를 사용하여 특정 Python 버전을 설치하고 프로젝트에서 관리할 수 있습니다.

  • 최신 안정 버전 Python 설치: 
    uv python install
    이 명령은 이용 가능한 최신 안정 버전 Python을 다운로드하고 설치합니다.
  • 특정 버전 설치: 
    uv python install 3.12
    이는 Python 3.12의 최신 패치 릴리스(예: 3.12.3)를 설치합니다.
  • 정확한 패치 버전 설치: 
    uv python install 3.12.3
    이는 정확히 Python 3.12.3을 설치합니다.
  • 여러 버전 설치: 
    uv python install 3.9 3.10 3.11
    이는 Python 3.9, 3.10, 3.11을 설치합니다.
  • 제약 조건에 맞는 버전 설치: 
    uv python install '>=3.8,=3.11"
    이는 프로젝트의 Python 버전 요구 사항을 변경합니다.

추가 노트

자동 다운로드: 기본적으로, 시스템에 필요한 Python 버전이 없으면 uv가 자동으로 다운로드하여 설치합니다.

시스템 Python: 기존에 설치된 Python이 있으면 uv가 이를 사용할 수 있으며, --no-managed-python 플래그를 사용하여 시스템 Python 사용을 강제할 수도 있습니다.

업그레이드: uv가 관리하는 Python 버전을 최신 패치 릴리스로 업그레이드할 수 있습니다:

uv python upgrade 3.12

또는 설치된 모든 버전을 업그레이드할 수 있습니다:

uv python upgrade

마이너 버전 간 업그레이드(예: 3.12에서 3.13으로)는 지원하지 않습니다.

요약하자면, uv는 프로젝트에서 특정 Python 버전을 설치, 관리, 사용하도록 유연하고 강력한 도구를 제공합니다.

UV는 다양한 시스템에서 이용 가능한 Python 인터프리터를 어떻게 발견하는가

UV는 일련의 잘 정의된 위치를 확인하고 각 후보 인터프리터의 버전 메타데이터를 조회함으로써 다양한 시스템에서 이용 가능한 Python 인터프리터를 발견합니다. 작동 원리는 다음과 같습니다:

  • 관리 대상 Python 설치:
    UV는 먼저 UV_PYTHON_INSTALL_DIR 환경 변수로 지정된 디렉터리를 확인합니다. 여기에는 UV가 자체적으로 관리하는 Python 버전들이 저장되어 있습니다.
  • 시스템 PATH:
    macOS와 Linux에서는 시스템 PATH에 나열된 디렉터리에 python, python3, 또는 python3.x(x는 버전 번호) 이름의 실행 파일이 있는지 확인합니다. Windows에서는 python.exe를 찾습니다.
  • Windows 전용 위치:
    Windows에서 UV는 Windows 레지스트리와 Microsoft Store의 Python 인터프리터도 py --list-paths의 출력을 사용하여 확인합니다.
  • 가상 환경:
    가상 환경이 활성화되어 있거나 지정되어 있으면, 다른 위치를 검색하기 전에 해당 환경의 인터프리터 호환성을 먼저 확인합니다.
  • 메타데이터 조회:
    발견된 각 실행 파일은 버전 메타데이터를 위해 조회됩니다. 요청된 버전(또는 버전 제약 조건)에 맞는 실행 파일만 고려됩니다. 실행할 수 없는 파일은 무시됩니다.
  • 선호도 및 폴백:
    기본적으로 UV는 시스템 Python 설치를 선호하지만, 옵션을 조정하여 관리 대상 버전을 선호하거나 관리 대상/시스템 버전만 사용하도록 설정할 수 있습니다. 적합한 인터프리터가 찾지 못하면 UV는 필요한 버전을 다운로드하여 설치할 수 있습니다.

이러한 견고한 발견 과정은 UV가 다양한 운영체제와 환경에서 올바른 Python 인터프리터를 안정적으로 찾아 사용할 수 있음을 보장합니다.

유용한 링크

구독하기

시스템, 인프라, AI 엔지니어링에 관한 새 글을 받아보세요.