[Python] Python 패키지 관리의 혁신, uv 사용 가이드 (V3 이슈 포함)

Python 패키지 관리의 혁신, uv 사용 가이드 (V3 이슈 포함)

파이썬 개발자라면 누구나 pip를 사용해 패키지를 설치해 보았을 것이다. 하지만 프로젝트가 복잡해질수록 의존성 관리는 점점 어려워지고, 설치 시간은 하염없이 길어지기도 한다. 이러한 문제들을 해결하기 위해 등장한 강력한 도구가 바로 uv이다.

이 글에서는 차세대 파이썬 패키지 관리 도구 uv가 무엇인지 알아보고, 기존 pip와의 차이점, 그리고 uv init, uv add, uv run 등의 명령어를 활용하여 pyproject.toml 파일을 중심으로 프로젝트를 진행하는 상세한 예제를 소개하고자 한다. 또한, uv run의 편리한 자동 환경 관리 기능과 가상 환경 직접 관리 방법까지 다룰 것이다.

1. uv란 무엇인가?

• uv는 Rust로 작성되어 매우 빠른 속도를 자랑하는 파이썬 패키지 설치 프로그램 및 해결 프로그램이다.
• 파이썬 코드 검사 도구 Ruff를 개발한 Astral 팀에서 개발하여 신뢰성을 더한다.
• 프로젝트 초기화(uv init), 의존성 관리(pyproject.toml 기반, uv add), 패키지 설치(uv pip install), 가상 환경 관리(uv venv), 명령어 실행(uv run) 등을 하나의 통합된 도구로 제공하는 것을 목표로 한다. 이는 기존의 pip, venv, pip-tools 등을 대체할 수 있는 잠재력을 지닌다.
• 공식 페이지([https://docs.astral.sh/uv/])

2. 왜 uv인가? (pip와의 비교)

uv는 기존 pip 중심의 워크플로우에 비해 다음과 같은 명확한 장점을 제공한다.

• 비교 불가능한 속도:
  • uv는 Rust의 성능과 효율적인 캐싱, 병렬 처리 기술을 통해 pip 대비 수십 배에서 수백 배 빠른 패키지 설치 및 의존성 해결 속도를 보여준다. 특히 복잡한 의존성을 가진 대규모 프로젝트에서 그 차이는 극명하다.
• pyproject.toml 중심의 통합 관리:
  • uv는 최신 파이썬 표준인 pyproject.toml 파일을 중심으로 프로젝트를 관리한다. uv init으로 프로젝트를 시작하고, uv add <package> 명령어를 통해 pyproject.toml에 직접 의존성을 추가하며 동시에 설치까지 완료한다.
  • 반면, pip는 주로 requirements.txt 파일을 사용하며, pyproject.toml과의 통합이나 가상 환경 관리는 별도의 도구(venv, pip-tools 등)에 의존해야 한다. uv는 이러한 작업들을 단일 인터페이스로 통합한다.
• 간결한 워크플로우:
  • 프로젝트 초기화, 의존성 정의, 설치, 환경 실행 등 프로젝트 관리의 여러 단계를 uv라는 하나의 도구로 처리할 수 있어 개발 워크플로우가 훨씬 간결하고 효율적이 된다.

속도와 편의성, 그리고 현대적인 pyproject.toml 기반의 프로젝트 관리를 원한다면 uv는 최고의 선택이 될 것이다.

3. uv 설치하기

권장 방법: pip 사용

시스템에 Python과 pip가 설치되어 있다면, 다음 명령어로 간단하게 uv를 설치할 수 있다. 이 방법이 가장 일반적이며, 아래에서 설명할 백신 문제를 피할 수 있다.

pip install uv

참고: PowerShell 설치 시 V3 백신 오탐 문제

uv 공식 문서에서는 PowerShell을 이용한 설치 방법도 안내한다.

# 주의: 이 명령어는 V3 등 일부 백신에서 오탐될 수 있다!
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

하지만 이 명령어는 인터넷에서 스크립트를 받아 바로 실행하는 방식 때문에, AhnLab V3와 같은 일부 백신에서 악성코드로 오탐(False Positive)하는 경우가 보고되었다. (실제로 악성코드가 아니다!)

만약 이 방법으로 설치 시 V3 경고가 발생한다면, pip install uv 방법을 사용하거나, V3 백신 설정에서 해당 스크립트나 파일 경로를 예외 처리하는 것을 권장한다.

4. uv와 pyproject.toml 사용 예제: 네이버 요청 프로젝트

이제 uv와 pyproject.toml을 사용하여 간단한 웹 요청 프로젝트를 만들어 보자.

• 1단계: 프로젝트 디렉토리 생성 및 이동

  mkdir example cd example

• 2단계: uv init으로 프로젝트 초기화

  • uv init 명령어는 현재 디렉토리에 pyproject.toml 파일을 생성하여 기본적인 프로젝트 구조를 설정한다. 프로젝트 이름, 버전 등을 설정하는 표준 pyproject.toml 파일이 만들어진다.

    uv init

• 3단계: uv add로 의존성 추가

  • uv add <package> 명령어는 해당 패키지를 pyproject.toml의 [project.dependencies] 목록에 자동으로 추가하고, 동시에 uv가 관리하는 가상 환경에 설치까지 완료한다. 프로젝트의 공식 의존성으로 등록하는 올바른 방법이다.

    uv add requests

  • 이 명령 실행 후 pyproject.toml 파일을 열어보면 dependencies 배열 안에 "requests" (버전 명시 포함)가 추가된 것을 확인할 수 있다.

• 4단계: Python 코드 작성 (main.py)

  • requests 라이브러리를 사용하여 네이버에 GET 요청을 보내는 간단한 파이썬 코드를 작성한다.

    import requests
    try:
        response = requests.get("https://www.naver.com")
        print(f"요청 성공! 상태 코드: {response.status_code}")
        response.raise_for_status() # 200 OK가 아니면 예외 발생
    except requests.exceptions.RequestException as e:
        print(f"요청 중 오류 발생: {e}")

• 5단계: uv run으로 코드 실행 및 자동 환경 관리 이해

  • uv run 명령어는 단순히 스크립트를 실행하는 것을 넘어, 실행 환경을 자동으로 준비한다.

    uv run main.py

  • 이 명령어를 실행하면 다음과 같은 일이 일어난다.

    1. 가상 환경 자동 생성/확인: uv는 .venv 가상 환경이 없으면 자동으로 생성한다. (Creating virtual environment at: .venv 로그 확인)
    2. 의존성 자동 설치/확인: pyproject.toml에 명시된 의존성(requests 등)이 .venv에 없으면 자동으로 설치한다. (Installed X packages... 로그 확인)
    3. 명령어 실행: 준비된 가상 환경 내에서 main.py를 실행하려고 시도한다.
       • 실행 방식: uv run main.py는 main.py를 직접 실행 가능한 파일로 간주하고 OS에 실행을 위임한다. (쉬뱅, 실행 권한, 파일 연결 등에 의존) 만약 이것이 성공하면 (PATH 등 uv가 설정한 환경 변수 덕분에) 가상 환경의 파이썬과 패키지를 사용하게 된다.
       • 권장 방식: 더 명확하고 플랫폼 간 호환성을 높이려면 uv run python main.py처럼 가상 환경 내의 python 인터프리터를 명시적으로 지정하는 것이 좋다.

  • 정상적으로 실행되면 터미널에 "요청 성공! 상태 코드: 200" 메시지가 출력될 것이다. uv run의 자동 환경 관리 덕분에 별도의 venv 생성이나 pip install 없이 바로 코드를 실행할 수 있다.

5. uv 가상 환경 직접 관리 (선택 사항)

uv run의 자동 관리가 편리하지만, 때로는 명시적으로 가상 환경을 제어해야 할 필요도 있다.

• 가상 환경 생성:

  • 프로젝트 루트에서 uv venv를 실행하면 .venv 가상 환경이 생성된다.

    uv venv

• 가상 환경 활성화:

  • 사용하는 쉘에 따라 다음 명령어로 활성화한다.

    • PowerShell:

      .\.venv\Scripts\activate

    • Bash / Zsh:

      source .venv/bin/activate

  • 활성화되면 프롬프트 앞에 (.venv)가 표시된다.

• 가상 환경 비활성화:

  deactivate

• 활성화 후 직접 실행:

  • 가상 환경이 활성화된 상태에서는 uv run 없이 표준 python 명령어로 스크립트를 실행할 수 있으며, 이때는 해당 가상 환경의 파이썬과 패키지를 사용한다.

    #.venv 활성화된 상태에서 실행
    python main.py

6. 마무리

uv는 압도적인 속도, pyproject.toml 중심의 현대적인 프로젝트 관리, 그리고 uv init, uv add, uv run, uv venv 등 일관되고 통합된 명령어 체계를 통해 파이썬 개발 경험을 한 단계 끌어올리는 강력한 도구이다. 특히 uv run의 자동 환경 관리 기능은 개발 초기 단계나 간단한 스크립트 실행 시 매우 편리하다.

기존 방식의 번거로움에서 벗어나 빠르고 효율적인 개발 환경을 구축하고 싶다면, uv 도입을 적극적으로 고려해볼 가치가 충분하다. 지금 바로 uv를 사용하여 생산성의 차이를 경험해보길 바란다.