Python 패키지/환경/버전 통합 관리 도구 UV 정리

개요

최근 파이썬 기반의 AI 에이전트 및 MCP 서버 등 다양한 프로젝트에서 UV라는 패키지 관리 도구가 활발히 사용되고 있다.

uv는 파이썬 패키지 설치, 가상환경 구성, 파이썬 버전관리 기능을 하나로 통합한 CLI 기반 도구이다.

https://github.com/astral-sh/uv

GitHub - astral-sh/uv: An extremely fast Python package and project manager, written in Rust.

 

UV

주요 특징

항목	설명
언어	Rust 기반의 pip 랩퍼
주요기능	패키지 설치, 가상환경 관리, 파이썬 버전관리 통합
특징	병렬 설치로 빠름, 별도의 툴 없이 통합 Python 프로젝트 운영 가능

 

설치

운영체제에 따라 다음 명령어를 이용하여 설치 할 수 있다.

 

Mac / LInux

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

 

Windows (PowerShell)

irm https://astral.sh/uv/install.ps1 | iex

 

설치 확인

uv --version

 

기본 사용법

프로젝트 초기화

uv init my-project
cd my-project

• 해당 코드 실행 시 pyproject.toml과 uv.lock 파일이 생성된다.

 

가상환경 구성 및 pip 설치

uv venv --python 3.11 --seed

• --python: 사용할 파이썬 버전 지정 (없으면 기본 python 버전 사용)
• --seed: 가상환경 내에 pip, setuptools, wheel 설치

 

패키지 추가

uv add pandas

• pyproject.toml에 dependency 항목이 자동 추가된다.
• uv.lock 파일도 함께 갱신된다.

 

패키지 제거

uv remove pandas

 

실행 및 관리

실행

uv run main.py

• 별도의 가상환경 활성화 과정 없이 실행 가능
• 프로젝트 루트의 가상환경을 자동 감지하여 사용함

 

Python 버전 변경

[project]
requires-python = ">=3.12"

• pyproject.toml에서 requires-python 항목 수정

uv venv --python 3.12 --seed

• 다음 명령어로 새로운 가장환경 재생성

 

패키지 잠금 (lock) 및 버전 고정

uv lock

• uv.lock 파일은 프로젝트에 설치된 모든 패키지의 버전 및 의존성을 기록한다.
• 이를 통해 requirements.txt 없이도 프로젝트 복제가 가능하다.

 

Github 프로젝트 복제 및 실행

git clone https://github.com/사용자명/프로젝트명.git
cd 프로젝트명
uv venv --seed
uv install
uv run main.py

• uv install은 pyproject.toml 및 uv.lock 기반으로 패키지를 재설치한다.

 

MCP 및 외부 툴 연동 예시

uv는 uvx를 통해 외부 패키지를 일시적으로 실행할 수 있는 기능을 제공한다.

uvx elevenlabs-mcp

• 해당 패키지가 PyPI에 등록되어 있어야 하며,
• 임시 가상환경이 자동 생성되어 실행된다.

 

결론

uv는 기존의 여러 파이썬 툴을 통합하여, 보다 일관되고 빠른 개발 환경을 제공한다.

특히 MCP 기반의 프로젝트나 다수의 패키지 버전이 얽힌 프로젝트에 적합하며,

향후 파이썬 생태계에서 널리 활용될 가능성이 높으니, 지금부터 잘 알아두고 쓰면 좋을듯 하다.